xnu-2422.1.72.tar.gz

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

<h2>thread_swap_exception_ports</h2>
<hr>
<p>
<strong>Function</strong> - Swap exception ports for a thread.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   thread_swap_exception_ports</strong>
                <strong>(thread_act_t</strong>                            <var>thread</var>,
                 <strong>exception_mask_t</strong>               <var>exception_types</var>,
                 <strong>mach_port_t</strong>                     <var>exception_port</var>,
                 <strong>exception_behavior_t</strong>                  <var>behavior</var>,
                 <strong>thread_state_flavor_t</strong>                   <var>flavor</var>,
                 <strong>exception_mask_array_t</strong>     <var>old_exception_masks</var>,
                 <strong>old_exception_masks</strong>        <var>old_exception_count</var>,
                 <strong>exception_port_array_t</strong>     <var>old_exception_ports</var>,
                 <strong>exception_behavior_array_t</strong>       <var>old_behaviors</var>,
                 <strong>exception_flavor_array_t</strong>           <var>old_flavors</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>thread</var> 
<dd>
[in thread send right]
The thread for which to set the ports.
<p>
<dt> <var>exception_types</var> 
<dd>
[in scalar]
A flag word indicating the types of exceptions for which the 
exception port applies:
<dl>
<p>
<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
<dd>
Could not access memory.
<p>
<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
<dd>
Instruction failed.  Illegal or undefined instruction or operand.
<p>
<dt> <strong>EXC_MASK_ARITHMETIC</strong>
<dd>
Arithmetic exception
<p>
<dt> <strong>EXC_MASK_EMULATION</strong>
<dd>
Emulation instruction.  Emulation support instruction
encountered.
<p>
<dt> <strong>EXC_MASK_SOFTWARE</strong>
<dd>
Software generated exception.
<p>
<dt> <strong>EXC_MASK_BREAKPOINT</strong>
<dd>
Trace, breakpoint, etc.
<p>
<dt> <strong>EXC_MASK_SYSCALL</strong>
<dd>
System call requested.
<p>
<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
<dd>
System call with a number in the Mach call range requested.
</dl>
<p>
<dt> <var>exception_port</var> 
<dd>
[in exception send right]
The exception port for all selected exception 
types.
<p>
<dt> <var>behavior</var> 
<dd>
[in scalar]
Control of the behavior of the exception processing.  Defined 
types are:
<dl>
<p>
<dt> <strong>EXCEPTION_DEFAULT</strong>
<dd>
Send a <strong>catch_exception_raise</strong> message including the thread 
identity.
<p>
<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
<dd>
Send a <strong>catch_exception_raise</strong> message including the thread 
identity.  Mark the exception port (and associated exceptions) 
as protected.
<p>
<dt> <strong>EXCEPTION_STATE</strong>
<dd>
Send a <strong>catch_exception_raise_state</strong> message including the 
thread state.
<p>
<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
<dd>
Send a <strong>catch_exception_raise_state</strong> message including the 
thread state.  Mark the exception port (and associated
exceptions) as protected.
<p>
<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
<dd>
Send a <strong>catch_exception_raise_state_identity</strong> message
including the thread identity and state.
<p>
<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
<dd>
Send a <strong>catch_exception_raise_state_identity</strong> message
including the thread identity and state.  Mark the exception port 
(and associated exceptions) as protected.
</dl>
<p>
<dt> <var>flavor</var> 
<dd>
[in scalar]
The type of state to be sent with the exception message. 
These types are defined in \*L<mach/thread_states.h>\*O.
<p>
<dt> <var>old_exception_masks</var> 
<dd>
[out array of <var>exception_mask_t</var>]
An array, each element being a mask 
specifying for which exception types the corresponding element of the 
other arrays apply.
<p>
<dt> <var>old_exception_count</var> 
<dd>
[pointer to in/out scalar]
On input, the maximum size of the array
buffers; on output, the number of returned <exception type mask,
exception port, behavior, flavor> sets returned.
<p>
<dt> <var>old_exception_ports</var> 
<dd>
[out array of exception send rights]
The returned exception ports.
<p>
<dt> <var>old_behaviors</var> 
<dd>
[out array of <var>exception_behavior_t</var>]
The type of exception message to 
be sent as with <var>behavior</var>.
<p>
<dt> <var>old_flavors</var> 
<dd>
[out array of <var>thread_state_flavor_t</var>]
The type of state to be sent with 
the exception message.  These types are defined in 
\*L<mach/thread_states.h>\*O.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>thread_swap_exception_ports</strong> function sets a specified
set of exception 
ports belonging to <var>thread</var>, returning the old set.
<h3>NOTES</h3>
<p>
If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is 
the host name port, Mach kernel traps are executed by the kernel as expected; 
any other value causes the attempted execution of these system call numbers to 
be considered an exception.
<p>
A "protected" exception port is one which cannot be fetched and for which
exception processing cannot be aborted (<strong>thread_abort</strong>).
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
<dd>
One of the requested exception ports is protected and cannot be returned.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
<a href="thread_create.html"><strong>thread_create</strong></a>,
<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
<a href="thread_abort.html"><strong>thread_abort</strong></a>.