-<h2>catch_exception_raise</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Handles the occurrence of an exception within a thread.
\r\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t catch_exception_raise</strong>
\r <strong>(mach_port_t</strong> <var>exception_port</var>,
\r <strong>mach_port_t</strong> <var>thread</var>,
\r <strong>mach_port_t</strong> <var>task</var>,
\r <strong>exception_type_t</strong> <var>exception</var>,
\r <strong>exception_data_t</strong> <var>code</var>,
\r <strong>mach_msg_type_number_t</strong> <var>code_count</var><strong>);</strong>
\r</pre>
\r<p>
\r<strong>catch_exception_raise_state</strong>
\rexpanded form:
\r<pre>
\r<strong>kern_return_t catch_exception_raise_state</strong>
\r <strong>(mach_port_t</strong> <var>exception_port</var>,
\r <strong>exception_type_t</strong> <var>exception</var>,
\r <strong>exception_data_t</strong> <var>code</var>,
\r <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
\r <strong>int *</strong> <var>flavor</var>,
\r <strong>thread_state_t</strong> <var>in_state</var>,
\r <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
\r <strong>thread_state_t</strong> <var>out_state</var>,
\r <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
\r</pre>
\r<p>
\r<strong>catch_exception_raise_state_identity</strong>
\rexpanded form:
\r<pre>
\r<strong>kern_return_t catch_exception_raise_state_identity</strong>
\r <strong>(mach_port_t</strong> <var>exception_port</var>,
\r <strong>mach_port_t</strong> <var>thread</var>,
\r <strong>mach_port_t</strong> <var>task</var>,
\r <strong>exception_type_t</strong> <var>exception</var>,
\r <strong>exception_data_t</strong> <var>code</var>,
\r <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
\r <strong>int *</strong> <var>flavor</var>,
\r <strong>thread_state_t</strong> <var>in_state</var>,
\r <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
\r <strong>thread_state_t</strong> <var>out_state</var>,
\r <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>exception_port</var>
\r<dd>
\r[in exception (receive) right] The port to which the exception
\rnotification was sent.
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread-self send right] The thread self port for the thread taking the
\rexception.
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task-self send right] The task self port for the task containing the
\rthread taking the exception.
\r<p>
\r<dt> <var>exception</var>
\r<dd>
\r[in scalar] The type of the exception.
\rThe machine independent values raised by all implementations are:
\r <dl>
\r<p>
\r<dt> EXC_BAD_ACCESS
\r<dd>
\rCould not access memory. subcode contains the bad memory
\raddress.
\r<p>
\r<dt> EXC_BAD_INSTRUCTION
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> EXC_ARITHMETIC
\r<dd>
\rArithmetic exception; exact nature of exception is in subcode
\rfield.
\r<p>
\r<dt> EXC_EMULATION
\r<dd>
\rEmulation instruction. Emulation support instruction encountered.
\rDetails in subcode field.
\r<p>
\r<dt> EXC_SOFTWARE
\r<dd>
\rSoftware generated exception; exact exception is in subcode
\rfield. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000
\r- 0x1FFFF reserved for OS emulation.
\r<p>
\r<dt> EXC_BREAKPOINT
\r<dd>
\rTrace, breakpoint, etc. Details in subcode field.
\r<p>
\r<dt> EXC_SYSCALL
\r<dd>
\rSystem call requested. Details in subcode field.
\r<p>
\r<dt> EXC_MACH_SYSCALL
\r<dd>
\rSystem call with a number in the Mach call range requested.
\rDetails in subcode field.
\r </dl
\r<p>
\r<dt> <var>code</var>
\r<dd>
\r[in scalar] A machine dependent array indicating a particular instance
\rof exception.
\r<p>
\r<dt> <var>code_count</var>
\r<dd>
\r[in scalar] The size of the buffer (in natural-sized units).
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[pointer to in/out scalar] On input, the type of state included as selected
\rwhen the exception port was set. On output, the type of state being
\rreturned.
\r<p>
\r<dt> <var>in_state</var>
\r<dd>
\r[pointer to in structure] State information of the thread at the time of
\rthe exception.
\r<p>
\r<dt> <var>in_state_count</var>
\r<dd>
\r[in scalar] The size of the in state buffer (in natural-sized units).
\r<p>
\r<dt> <var>out_state</var>
\r<dd>
\r[out structure] The state the thread will have if continued from the
\rpoint of the exception. The maximum size of this array is
\rTHREAD_STATE_MAX.
\r<p>
\r<dt> <var>out_state_count</var>
\r<dd>
\r[pointer to out scalar] The size of the out state buffer (in natural-sized units).
\r </dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>catch_exception_raise</strong> function is called by
\r<strong>exc_server</strong> as the result of a
\rkernel message indicating that an exception occurred within a thread.
\rThe <var>exception_port</var> parameter specifies the port named via
\ra previous call to <strong>thread_set_exception_ports</strong> or
\r<strong>task_set_exception_ports</strong>
\ras the port that responds when the thread takes an
\rexception.
\r<p>
\rThe alternate message forms (the format being selected when the exception port
\rwas set) allow for selected thread state to be included.
\r\r<h3>NOTES</h3>
\r<p>
\rWhen an exception occurs in a thread, the thread sends an exception message to
\rits exception port, blocking in the kernel waiting for the receipt of a reply. It is
\rassumed that some task is listening
\r(most likely with <strong>mach_msg_server</strong>) to this
\rport, using the <strong>exc_server</strong> function
\rto decode the messages and then call the
\rlinked in <strong>catch_exception_raise</strong>.
\rIt is the job of <strong>catch_exception_raise</strong> to handle
\rthe exception and decide the course of action for thread.
\r <p>
\rIf the thread should continue from the point of exception,
\r<strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply
\rmessage to be sent to the kernel, which will allow the thread to continue from
\rthe point of the exception.
\rIf some other action should be taken by thread, the following actions should be
\rperformed by <strong>catch_exception_raise</strong>:
\r <dl>
\r <dt> <strong>thread_suspend</strong>
\r <dd>
\r This keeps the thread from proceeding after the next step.
\r <p>
\r<dt> <strong>thread_abort</strong>
\r <dd>
\r This aborts the message receive operation currently blocking
\rthe thread.
\r <p>
\r<dt> <strong>thread_set_state</strong>
\r <dd>
\r (if using the <strong>catch_exception_raise</strong> form). Set the
\rthread's state so that it continues doing something else.
\r <p>
\r <dt> <strong>thread_resume</strong>
\r <dd>
\r Let the thread start running from its new state.
\r</dl>
\rReturning a value other than KERN_SUCCESS insures that no reply message
\rwill be sent.
\rsent. (Actually, the kernel uses a send once right to send the exception
\rmessage, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.)
\rThe thread can always be destroyed with <strong>thread_terminate</strong>.
\r<p>
\rA thread can have two exception ports active for it: its thread type specific exception
\rport and the task type specific exception port. The kernel will try sending
\ran exception message to both ports looking for a reply message with a
\rreturn value of KERN_SUCCESS. The kernel tries the thread specific port first,
\rthen the task specific port. If the return value from the first exception message
\rthe kernel sends has a return value of KERN_SUCCESS, the thread continues
\r(with a possibly modified state). If the return value is not KERN_SUCCESS,
\rthe kernel tries the second port. If that return value is KERN_SUCCESS, the
\rthread continues; otherwise, the thread is terminated.
\r<p>
\rTo get the effect of a non-success return value, the server interface should return
\rMIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong>
\rto destroy the kernel's request (as opposed to sending a reply with a
\rKERN_SUCCESS value).
\r\r<h3>RETURN VALUES</h3>
\r<p>
\rA return value of KERN_SUCCESS indicates that the thread is to continue
\rfrom the point of exception. A return value of MIG_NO_REPLY indicates that
\rthe exception was handled directly and the thread was restarted or terminated by
\rthe exception handler. A return value of MIG_DESTROY_REQUEST causes
\rthe kernel to try another exception handler (or terminate the thread). Any other
\rvalue will cause
\r<strong>mach_msg_server</strong> to remove the task and thread port references.
\r\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="exc_server.html"><strong>exc_server</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>,
\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
\r\ No newline at end of file
+<h2>catch_exception_raise</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Handles the occurrence of an exception within a thread.
+
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t catch_exception_raise</strong>
+ <strong>(mach_port_t</strong> <var>exception_port</var>,
+ <strong>mach_port_t</strong> <var>thread</var>,
+ <strong>mach_port_t</strong> <var>task</var>,
+ <strong>exception_type_t</strong> <var>exception</var>,
+ <strong>exception_data_t</strong> <var>code</var>,
+ <strong>mach_msg_type_number_t</strong> <var>code_count</var><strong>);</strong>
+</pre>
+<p>
+<strong>catch_exception_raise_state</strong>
+expanded form:
+<pre>
+<strong>kern_return_t catch_exception_raise_state</strong>
+ <strong>(mach_port_t</strong> <var>exception_port</var>,
+ <strong>exception_type_t</strong> <var>exception</var>,
+ <strong>exception_data_t</strong> <var>code</var>,
+ <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
+ <strong>int *</strong> <var>flavor</var>,
+ <strong>thread_state_t</strong> <var>in_state</var>,
+ <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
+ <strong>thread_state_t</strong> <var>out_state</var>,
+ <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
+</pre>
+<p>
+<strong>catch_exception_raise_state_identity</strong>
+expanded form:
+<pre>
+<strong>kern_return_t catch_exception_raise_state_identity</strong>
+ <strong>(mach_port_t</strong> <var>exception_port</var>,
+ <strong>mach_port_t</strong> <var>thread</var>,
+ <strong>mach_port_t</strong> <var>task</var>,
+ <strong>exception_type_t</strong> <var>exception</var>,
+ <strong>exception_data_t</strong> <var>code</var>,
+ <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
+ <strong>int *</strong> <var>flavor</var>,
+ <strong>thread_state_t</strong> <var>in_state</var>,
+ <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
+ <strong>thread_state_t</strong> <var>out_state</var>,
+ <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>exception_port</var>
+<dd>
+[in exception (receive) right] The port to which the exception
+notification was sent.
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread-self send right] The thread self port for the thread taking the
+exception.
+<p>
+<dt> <var>task</var>
+<dd>
+[in task-self send right] The task self port for the task containing the
+thread taking the exception.
+<p>
+<dt> <var>exception</var>
+<dd>
+[in scalar] The type of the exception.
+The machine independent values raised by all implementations are:
+ <dl>
+<p>
+<dt> EXC_BAD_ACCESS
+<dd>
+Could not access memory. subcode contains the bad memory
+address.
+<p>
+<dt> EXC_BAD_INSTRUCTION
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> EXC_ARITHMETIC
+<dd>
+Arithmetic exception; exact nature of exception is in subcode
+field.
+<p>
+<dt> EXC_EMULATION
+<dd>
+Emulation instruction. Emulation support instruction encountered.
+Details in subcode field.
+<p>
+<dt> EXC_SOFTWARE
+<dd>
+Software generated exception; exact exception is in subcode
+field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000
+- 0x1FFFF reserved for OS emulation.
+<p>
+<dt> EXC_BREAKPOINT
+<dd>
+Trace, breakpoint, etc. Details in subcode field.
+<p>
+<dt> EXC_SYSCALL
+<dd>
+System call requested. Details in subcode field.
+<p>
+<dt> EXC_MACH_SYSCALL
+<dd>
+System call with a number in the Mach call range requested.
+Details in subcode field.
+ </dl
+<p>
+<dt> <var>code</var>
+<dd>
+[in scalar] A machine dependent array indicating a particular instance
+of exception.
+<p>
+<dt> <var>code_count</var>
+<dd>
+[in scalar] The size of the buffer (in natural-sized units).
+<p>
+<dt> <var>flavor</var>
+<dd>
+[pointer to in/out scalar] On input, the type of state included as selected
+when the exception port was set. On output, the type of state being
+returned.
+<p>
+<dt> <var>in_state</var>
+<dd>
+[pointer to in structure] State information of the thread at the time of
+the exception.
+<p>
+<dt> <var>in_state_count</var>
+<dd>
+[in scalar] The size of the in state buffer (in natural-sized units).
+<p>
+<dt> <var>out_state</var>
+<dd>
+[out structure] The state the thread will have if continued from the
+point of the exception. The maximum size of this array is
+THREAD_STATE_MAX.
+<p>
+<dt> <var>out_state_count</var>
+<dd>
+[pointer to out scalar] The size of the out state buffer (in natural-sized units).
+ </dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>catch_exception_raise</strong> function is called by
+<strong>exc_server</strong> as the result of a
+kernel message indicating that an exception occurred within a thread.
+The <var>exception_port</var> parameter specifies the port named via
+a previous call to <strong>thread_set_exception_ports</strong> or
+<strong>task_set_exception_ports</strong>
+as the port that responds when the thread takes an
+exception.
+<p>
+The alternate message forms (the format being selected when the exception port
+was set) allow for selected thread state to be included.
+
+<h3>NOTES</h3>
+<p>
+When an exception occurs in a thread, the thread sends an exception message to
+its exception port, blocking in the kernel waiting for the receipt of a reply. It is
+assumed that some task is listening
+(most likely with <strong>mach_msg_server</strong>) to this
+port, using the <strong>exc_server</strong> function
+to decode the messages and then call the
+linked in <strong>catch_exception_raise</strong>.
+It is the job of <strong>catch_exception_raise</strong> to handle
+the exception and decide the course of action for thread.
+ <p>
+If the thread should continue from the point of exception,
+<strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply
+message to be sent to the kernel, which will allow the thread to continue from
+the point of the exception.
+If some other action should be taken by thread, the following actions should be
+performed by <strong>catch_exception_raise</strong>:
+ <dl>
+ <dt> <strong>thread_suspend</strong>
+ <dd>
+ This keeps the thread from proceeding after the next step.
+ <p>
+<dt> <strong>thread_abort</strong>
+ <dd>
+ This aborts the message receive operation currently blocking
+the thread.
+ <p>
+<dt> <strong>thread_set_state</strong>
+ <dd>
+ (if using the <strong>catch_exception_raise</strong> form). Set the
+thread's state so that it continues doing something else.
+ <p>
+ <dt> <strong>thread_resume</strong>
+ <dd>
+ Let the thread start running from its new state.
+</dl>
+Returning a value other than KERN_SUCCESS insures that no reply message
+will be sent.
+sent. (Actually, the kernel uses a send once right to send the exception
+message, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.)
+The thread can always be destroyed with <strong>thread_terminate</strong>.
+<p>
+A thread can have two exception ports active for it: its thread type specific exception
+port and the task type specific exception port. The kernel will try sending
+an exception message to both ports looking for a reply message with a
+return value of KERN_SUCCESS. The kernel tries the thread specific port first,
+then the task specific port. If the return value from the first exception message
+the kernel sends has a return value of KERN_SUCCESS, the thread continues
+(with a possibly modified state). If the return value is not KERN_SUCCESS,
+the kernel tries the second port. If that return value is KERN_SUCCESS, the
+thread continues; otherwise, the thread is terminated.
+<p>
+To get the effect of a non-success return value, the server interface should return
+MIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong>
+to destroy the kernel's request (as opposed to sending a reply with a
+KERN_SUCCESS value).
+
+<h3>RETURN VALUES</h3>
+<p>
+A return value of KERN_SUCCESS indicates that the thread is to continue
+from the point of exception. A return value of MIG_NO_REPLY indicates that
+the exception was handled directly and the thread was restarted or terminated by
+the exception handler. A return value of MIG_DESTROY_REQUEST causes
+the kernel to try another exception handler (or terminate the thread). Any other
+value will cause
+<strong>mach_msg_server</strong> to remove the task and thread port references.
+
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="exc_server.html"><strong>exc_server</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>,
+<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
+<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
+<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
+<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
projects / apple / xnu.git / blobdiff