[apple/xnu.git] / osfmk / man / thread_set_exception_ports.html

<h2>thread_set_exception_ports</h2>\r<hr>\r<p>\r<strong>Function</strong> - Set exception ports for a thread.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   thread_set_exception_ports</strong>\r                <strong>(thread_act_t</strong>                            <var>thread</var>,\r                 <strong>exception_mask_t</strong>               <var>exception_types</var>,\r                 <strong>mach_port_t</strong>                     <var>exception_port</var>,\r                 <strong>exception_behavior_t</strong>                  <var>behavior</var>,\r                 <strong>thread_state_flavor_t</strong>                   <var>flavor</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>thread</var> \r<dd>\r[in thread send right]\rThe thread for which to set the ports.\r<p>\r<dt> <var>exception_types</var> \r<dd>\r[in scalar]\rA flag word indicating the types of exceptions for which the \rexception port applies:\r<dl>\r<p>\r<dt> <strong>EXC_MASK_BAD_ACCESS</strong>\r<dd>\rCould not access memory.\r<p>\r<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>\r<dd>\rInstruction failed.  Illegal or undefined instruction or operand.\r<p>\r<dt> <strong>EXC_MASK_ARITHMETIC</strong>\r<dd>\rArithmetic exception.\r<p>\r<dt> <strong>EXC_MASK_EMULATION</strong>\r<dd>\rEmulation instruction.  Emulation support instruction\rencountered.\r<p>\r<dt> <strong>EXC_MASK_SOFTWARE</strong>\r<dd>\rSoftware generated exception.\r<p>\r<dt> <strong>EXC_MASK_BREAKPOINT</strong>\r<dd>\rTrace, breakpoint, etc.\r<p>\r<dt> <strong>EXC_MASK_SYSCALL</strong>\r<dd>\rSystem call requested.\r<p>\r<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>\r<dd>\rSystem call with a number in the Mach call range requested.\r</dl>\r<p>\r<dt> <var>exception_port</var> \r<dd>\r[in exception send right]\rThe exception port for all selected exception \rtypes.\r<p>\r<dt> <var>behavior</var> \r<dd>\r[in scalar]\rThe type of exception message to be sent.  Defined types are:\r<dl>\r<p>\r<dt> <strong>EXCEPTION_DEFAULT</strong>\r<dd>\rSend a <strong>catch_exception_raise</strong> message including the thread \ridentity.\r<p>\r<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>\r<dd>\rSend a <strong>catch_exception_raise</strong> message including the thread \ridentity.  Mark the exception port (and associated exceptions) \ras protected.\r<p>\r<dt> <strong>EXCEPTION_STATE</strong>\r<dd>\rSend a <strong>catch_exception_raise_state</strong> message including the \rthread state.\r<p>\r<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>\r<dd>\rSend a <strong>catch_exception_raise_state</strong> message including the \rthread state.  Mark the exception port (and associated\rexceptions) as protected.\r<p>\r<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>\r<dd>\rSend a <strong>catch_exception_raise_state_identity</strong> message\rincluding the thread identity and state.\r<p>\r<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>\r<dd>\rSend a <strong>catch_exception_raise_state_identity</strong> message\rincluding the thread identity and state.  Mark the exception port \r(and associated exceptions) as protected.\r</dl>\r<p>\r<dt> <var>flavor</var> \r<dd>\r[in scalar]\rThe type of state to be sent with the exception message. \rThese types are defined in \*L<mach/thread_states.h>\*O.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>thread_set_exception_ports</strong> function sets a specified\rset of exception \rports belonging to <var>thread</var>.\r<h3>NOTES</h3>\r<p>\rIf the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is \rthe host name port, Mach kernel traps are executed by the kernel as expected; \rany other value causes the attempted execution of these system call numbers to \rbe considered an exception.\r<p>\rA "protected" exception port is one which cannot be fetched and for which\rexception processing cannot be aborted (<strong>thread_abort</strong>).\r<h3>RETURN VALUES</h3>\r<p>\rOnly generic errors apply.\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,\r<a href="thread_create.html"><strong>thread_create</strong></a>,\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,\r<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,\r<a href="thread_abort.html"><strong>thread_abort</strong></a>.\r