1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../../../css/manpage.css" type="text/css" />
7<title>SetUserExceptionHandler</title>
8  </head>
9  <body>
10<h1><CODE><a href="../../../nn/Overview.html">nn</a>::<a href="../../../nn/os/Overview.html">os</a>::<a href="../../../nn/os/ARM/Overview.html">ARM</a>::SetUserExceptionHandler</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14void SetUserExceptionHandler(
15     <a href="../../../nn/os/ARM/UserExceptionHandler.html">UserExceptionHandler</a> pHandler,
16     <a href="../../../nn_types/uptr.html">uptr</a> stackBottom,
17     <a href="../../../nn/os/ARM/ExceptionBuffer/Overview.html">ExceptionBuffer</a> * pExceptionBuffer
18);
19</pre>
20    </div>
21<h2>Parameters</h2>
22    <div class="section">
23      <table class="arguments">
24        <thead>
25          <tr>
26            <td width="15" />
27<th>Name</th>
28<td>Description</td>
29          </tr>
30        </thead>
31        <tr>
32<td>in</td>
33<th>pHandler</th>
34<td>Specifies the exception handler called when an exception occurs.</td>
35        </tr>
36        <tr>
37<td>in</td>
38<th>stackBottom</th>
39<td>Specifies the stack to use for the exception handler. You must specify the bottom of the stack.</td>
40        </tr>
41        <tr>
42<td>in</td>
43<th><CODE>pExceptionBuffer</CODE></th>
44<td>Specifies a buffer for storing exception information.</td>
45        </tr> </table>
46    </div>
47<h2>Return Values</h2>
48    <div class="section">
49None.
50               </div>
51<h2>Description</h2>
52    <div class="section">
53<p>Specifies the global exception handler.</p><h4>Arguments</h4><p>
54If <a href="../../../nn/os/ARM/HANDLER_STACK_USE_THREAD_STACK.html"><CODE>HANDLER_STACK_USE_THREAD_STACK</CODE></a> is specified for <CODE>stackBottom</CODE>, the stack for the thread in which the exception occurred is used as-is as the exception handler stack.
55            </p><p>
56The instances of <a href="../../../nn/os/ARM/ExceptionInfo/Overview.html"><CODE>ExceptionInfo</CODE></a> and <a href="../../../nn/os/ARM/ExceptionContext/Overview.html"><CODE>ExceptionContext</CODE></a>, passed to the handler given by <SPAN class="argument">pHandler</SPAN>, are allocated from the buffer specified by <SPAN class="argument">pExceptionBuffer</SPAN>. If <a href="../../../nn/os/ARM/Overview.html"><CODE>EXCEPTION_BUFFER_USE_HANDLER_STACK</CODE></a> is specified in <CODE>pExceptionBuffer</CODE>, they are allocated from the exception handler stack. If <a href="../../../nn/os/ARM/Overview.html">EXCEPTION_BUFFER_USE_THREAD_STACK</a> is specified in <CODE>pExceptionBuffer</CODE>, they are allocated from the stack for the thread in which the exception occurred.
57</p><h4>Exception Handler Settings</h4><p>
58Exception handler settings exist for each thread. If an exception occurs, an exception handler is called based on the settings for the thread in question. If an exception handler has not been set for the particular thread in question, an exception handler based on settings for the main thread is called.
59            </p><p>
60The global exception handler refers to the exception handler for the main thread. This function sets the exception handler for the main thread.
61            </p><p>
62When an exception handler is specified and an exception occurs, the function specified by the <SPAN class="argument">pHandler</SPAN> parameter is called in the context of the thread where the exception occurred. However, the stack gets replaced by the stack specified by <SPAN class="argument">stackBottom</SPAN>.
63            </p><p>
64Note that special processing, such as disabling interrupts, is not used when calling the exception handler. If the same memory is set for more than one thread as a buffer for storing the exception handler stack and exception information, and if an exception occurs in one thread that shares this memory while the exception handler is executing for another of these threads, the exception handler stack and buffer for exception information will be destroyed.
65</p><h4>Exception Handler Implementation</h4><p>
66Exception handlers have the following restrictions.
67</p><ul><li>Control cannot return from an exception handler. A return statement will lead to undefined behavior.</li><li>Exception handlers must be compiled with ARM instructions. You cannot use exception handlers that have THUMB instructions. Exception handlers are allowed to call functions that have THUMB instructions.</li></ul><p>
68Note that the exception handler cannot be called in the debug environment.
69</p><h4>Thread Safety</h4><p>
70This function is not thread-safe at the function level. It also requires mutual exclusion with the <CODE><a href="../../../nn/os/ARM/SetUserExceptionHandlerLocal.html">SetUserExceptionHandlerLocal</a></CODE> function called in the main thread.
71            </p></div>
72<h2>Revision History</h2>
73    <div class="section">
74      <dl class="history">
75        <dt>2012/04/23</dt>
76<dd>Added a description about thread safety.<br />
77        </dd>
78        <dt>2011/10/12</dt>
79<dd>Added restrictions about exception handlers.<br />
80        </dd>
81        <dt>2011/05/02</dt>
82<dd>Modified wording to read &quot;to the stack specified by <CODE>stackBottom</CODE>&quot; rather than just &quot;to <CODE>stackBottom</CODE>.&quot;
83        </dd>
84        <dt>2010/09/16</dt>
85<dd>Added mention that the exception handler is not called in the debug environment.<br />
86        </dd>
87        <dt>2010/08/16</dt>
88<dd>Initial version.<br />
89        </dd>
90      </dl>
91    </div>
92  <hr><p>CONFIDENTIAL</p></body>
93</html>