1<h2>thread_swap_exception_ports</h2>
2<hr>
3<p>
4<strong>Function</strong> - Swap exception ports for a thread.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   thread_swap_exception_ports</strong>
8                <strong>(thread_act_t</strong>                            <var>thread</var>,
9                 <strong>exception_mask_t</strong>               <var>exception_types</var>,
10                 <strong>mach_port_t</strong>                     <var>exception_port</var>,
11                 <strong>exception_behavior_t</strong>                  <var>behavior</var>,
12                 <strong>thread_state_flavor_t</strong>                   <var>flavor</var>,
13                 <strong>exception_mask_array_t</strong>     <var>old_exception_masks</var>,
14                 <strong>old_exception_masks</strong>        <var>old_exception_count</var>,
15                 <strong>exception_port_array_t</strong>     <var>old_exception_ports</var>,
16                 <strong>exception_behavior_array_t</strong>       <var>old_behaviors</var>,
17                 <strong>exception_flavor_array_t</strong>           <var>old_flavors</var><strong>);</strong>
18</pre>
19<h3>PARAMETERS</h3>
20<dl>
21<p>
22<dt> <var>thread</var> 
23<dd>
24[in thread send right]
25The thread for which to set the ports.
26<p>
27<dt> <var>exception_types</var> 
28<dd>
29[in scalar]
30A flag word indicating the types of exceptions for which the 
31exception port applies:
32<dl>
33<p>
34<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
35<dd>
36Could not access memory.
37<p>
38<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
39<dd>
40Instruction failed.  Illegal or undefined instruction or operand.
41<p>
42<dt> <strong>EXC_MASK_ARITHMETIC</strong>
43<dd>
44Arithmetic exception
45<p>
46<dt> <strong>EXC_MASK_EMULATION</strong>
47<dd>
48Emulation instruction.  Emulation support instruction
49encountered.
50<p>
51<dt> <strong>EXC_MASK_SOFTWARE</strong>
52<dd>
53Software generated exception.
54<p>
55<dt> <strong>EXC_MASK_BREAKPOINT</strong>
56<dd>
57Trace, breakpoint, etc.
58<p>
59<dt> <strong>EXC_MASK_SYSCALL</strong>
60<dd>
61System call requested.
62<p>
63<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
64<dd>
65System call with a number in the Mach call range requested.
66</dl>
67<p>
68<dt> <var>exception_port</var> 
69<dd>
70[in exception send right]
71The exception port for all selected exception 
72types.
73<p>
74<dt> <var>behavior</var> 
75<dd>
76[in scalar]
77Control of the behavior of the exception processing.  Defined 
78types are:
79<dl>
80<p>
81<dt> <strong>EXCEPTION_DEFAULT</strong>
82<dd>
83Send a <strong>catch_exception_raise</strong> message including the thread 
84identity.
85<p>
86<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
87<dd>
88Send a <strong>catch_exception_raise</strong> message including the thread 
89identity.  Mark the exception port (and associated exceptions) 
90as protected.
91<p>
92<dt> <strong>EXCEPTION_STATE</strong>
93<dd>
94Send a <strong>catch_exception_raise_state</strong> message including the 
95thread state.
96<p>
97<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
98<dd>
99Send a <strong>catch_exception_raise_state</strong> message including the 
100thread state.  Mark the exception port (and associated
101exceptions) as protected.
102<p>
103<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
104<dd>
105Send a <strong>catch_exception_raise_state_identity</strong> message
106including the thread identity and state.
107<p>
108<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
109<dd>
110Send a <strong>catch_exception_raise_state_identity</strong> message
111including the thread identity and state.  Mark the exception port 
112(and associated exceptions) as protected.
113</dl>
114<p>
115<dt> <var>flavor</var> 
116<dd>
117[in scalar]
118The type of state to be sent with the exception message. 
119These types are defined in \*L<mach/thread_states.h>\*O.
120<p>
121<dt> <var>old_exception_masks</var> 
122<dd>
123[out array of <var>exception_mask_t</var>]
124An array, each element being a mask 
125specifying for which exception types the corresponding element of the 
126other arrays apply.
127<p>
128<dt> <var>old_exception_count</var> 
129<dd>
130[pointer to in/out scalar]
131On input, the maximum size of the array
132buffers; on output, the number of returned <exception type mask,
133exception port, behavior, flavor> sets returned.
134<p>
135<dt> <var>old_exception_ports</var> 
136<dd>
137[out array of exception send rights]
138The returned exception ports.
139<p>
140<dt> <var>old_behaviors</var> 
141<dd>
142[out array of <var>exception_behavior_t</var>]
143The type of exception message to 
144be sent as with <var>behavior</var>.
145<p>
146<dt> <var>old_flavors</var> 
147<dd>
148[out array of <var>thread_state_flavor_t</var>]
149The type of state to be sent with 
150the exception message.  These types are defined in 
151\*L<mach/thread_states.h>\*O.
152</dl>
153<h3>DESCRIPTION</h3>
154<p>
155The <strong>thread_swap_exception_ports</strong> function sets a specified
156set of exception 
157ports belonging to <var>thread</var>, returning the old set.
158<h3>NOTES</h3>
159<p>
160If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is 
161the host name port, Mach kernel traps are executed by the kernel as expected; 
162any other value causes the attempted execution of these system call numbers to 
163be considered an exception.
164<p>
165A "protected" exception port is one which cannot be fetched and for which
166exception processing cannot be aborted (<strong>thread_abort</strong>).
167<h3>RETURN VALUES</h3>
168<dl>
169<p>
170<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
171<dd>
172One of the requested exception ports is protected and cannot be returned.
173</dl>
174<h3>RELATED INFORMATION</h3>
175<p>
176Functions:
177<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
178<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
179<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
180<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
181<a href="thread_create.html"><strong>thread_create</strong></a>,
182<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
183<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
184<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
185<a href="thread_abort.html"><strong>thread_abort</strong></a>.
186