1<h2>catch_exception_raise</h2> 2<hr> 3<p> 4<strong>Server Interface</strong> - Handles the occurrence of an exception within a thread. 5 6<h3>SYNOPSIS</h3> 7<pre> 8<strong>kern_return_t catch_exception_raise</strong> 9 <strong>(mach_port_t</strong> <var>exception_port</var>, 10 <strong>mach_port_t</strong> <var>thread</var>, 11 <strong>mach_port_t</strong> <var>task</var>, 12 <strong>exception_type_t</strong> <var>exception</var>, 13 <strong>exception_data_t</strong> <var>code</var>, 14 <strong>mach_msg_type_number_t</strong> <var>code_count</var><strong>);</strong> 15</pre> 16<p> 17<strong>catch_exception_raise_state</strong> 18expanded form: 19<pre> 20<strong>kern_return_t catch_exception_raise_state</strong> 21 <strong>(mach_port_t</strong> <var>exception_port</var>, 22 <strong>exception_type_t</strong> <var>exception</var>, 23 <strong>exception_data_t</strong> <var>code</var>, 24 <strong>mach_msg_type_number_t</strong> <var>code_count</var>, 25 <strong>int *</strong> <var>flavor</var>, 26 <strong>thread_state_t</strong> <var>in_state</var>, 27 <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>, 28 <strong>thread_state_t</strong> <var>out_state</var>, 29 <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong> 30</pre> 31<p> 32<strong>catch_exception_raise_state_identity</strong> 33expanded form: 34<pre> 35<strong>kern_return_t catch_exception_raise_state_identity</strong> 36 <strong>(mach_port_t</strong> <var>exception_port</var>, 37 <strong>mach_port_t</strong> <var>thread</var>, 38 <strong>mach_port_t</strong> <var>task</var>, 39 <strong>exception_type_t</strong> <var>exception</var>, 40 <strong>exception_data_t</strong> <var>code</var>, 41 <strong>mach_msg_type_number_t</strong> <var>code_count</var>, 42 <strong>int *</strong> <var>flavor</var>, 43 <strong>thread_state_t</strong> <var>in_state</var>, 44 <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>, 45 <strong>thread_state_t</strong> <var>out_state</var>, 46 <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong> 47</pre> 48<h3>PARAMETERS</h3> 49<dl> 50<dt> <var>exception_port</var> 51<dd> 52[in exception (receive) right] The port to which the exception 53notification was sent. 54<p> 55<dt> <var>thread</var> 56<dd> 57[in thread-self send right] The thread self port for the thread taking the 58exception. 59<p> 60<dt> <var>task</var> 61<dd> 62[in task-self send right] The task self port for the task containing the 63thread taking the exception. 64<p> 65<dt> <var>exception</var> 66<dd> 67[in scalar] The type of the exception. 68The machine independent values raised by all implementations are: 69 <dl> 70<p> 71<dt> EXC_BAD_ACCESS 72<dd> 73Could not access memory. subcode contains the bad memory 74address. 75<p> 76<dt> EXC_BAD_INSTRUCTION 77<dd> 78Instruction failed. Illegal or undefined instruction or operand. 79<p> 80<dt> EXC_ARITHMETIC 81<dd> 82Arithmetic exception; exact nature of exception is in subcode 83field. 84<p> 85<dt> EXC_EMULATION 86<dd> 87Emulation instruction. Emulation support instruction encountered. 88Details in subcode field. 89<p> 90<dt> EXC_SOFTWARE 91<dd> 92Software generated exception; exact exception is in subcode 93field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000 94- 0x1FFFF reserved for OS emulation. 95<p> 96<dt> EXC_BREAKPOINT 97<dd> 98Trace, breakpoint, etc. Details in subcode field. 99<p> 100<dt> EXC_SYSCALL 101<dd> 102System call requested. Details in subcode field. 103<p> 104<dt> EXC_MACH_SYSCALL 105<dd> 106System call with a number in the Mach call range requested. 107Details in subcode field. 108 </dl 109<p> 110<dt> <var>code</var> 111<dd> 112[in scalar] A machine dependent array indicating a particular instance 113of exception. 114<p> 115<dt> <var>code_count</var> 116<dd> 117[in scalar] The size of the buffer (in natural-sized units). 118<p> 119<dt> <var>flavor</var> 120<dd> 121[pointer to in/out scalar] On input, the type of state included as selected 122when the exception port was set. On output, the type of state being 123returned. 124<p> 125<dt> <var>in_state</var> 126<dd> 127[pointer to in structure] State information of the thread at the time of 128the exception. 129<p> 130<dt> <var>in_state_count</var> 131<dd> 132[in scalar] The size of the in state buffer (in natural-sized units). 133<p> 134<dt> <var>out_state</var> 135<dd> 136[out structure] The state the thread will have if continued from the 137point of the exception. The maximum size of this array is 138THREAD_STATE_MAX. 139<p> 140<dt> <var>out_state_count</var> 141<dd> 142[pointer to out scalar] The size of the out state buffer (in natural-sized units). 143 </dl> 144<h3>DESCRIPTION</h3> 145<p> 146A <strong>catch_exception_raise</strong> function is called by 147<strong>exc_server</strong> as the result of a 148kernel message indicating that an exception occurred within a thread. 149The <var>exception_port</var> parameter specifies the port named via 150a previous call to <strong>thread_set_exception_ports</strong> or 151<strong>task_set_exception_ports</strong> 152as the port that responds when the thread takes an 153exception. 154<p> 155The alternate message forms (the format being selected when the exception port 156was set) allow for selected thread state to be included. 157 158<h3>NOTES</h3> 159<p> 160When an exception occurs in a thread, the thread sends an exception message to 161its exception port, blocking in the kernel waiting for the receipt of a reply. It is 162assumed that some task is listening 163(most likely with <strong>mach_msg_server</strong>) to this 164port, using the <strong>exc_server</strong> function 165to decode the messages and then call the 166linked in <strong>catch_exception_raise</strong>. 167It is the job of <strong>catch_exception_raise</strong> to handle 168the exception and decide the course of action for thread. 169 <p> 170If the thread should continue from the point of exception, 171<strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply 172message to be sent to the kernel, which will allow the thread to continue from 173the point of the exception. 174If some other action should be taken by thread, the following actions should be 175performed by <strong>catch_exception_raise</strong>: 176 <dl> 177 <dt> <strong>thread_suspend</strong> 178 <dd> 179 This keeps the thread from proceeding after the next step. 180 <p> 181<dt> <strong>thread_abort</strong> 182 <dd> 183 This aborts the message receive operation currently blocking 184the thread. 185 <p> 186<dt> <strong>thread_set_state</strong> 187 <dd> 188 (if using the <strong>catch_exception_raise</strong> form). Set the 189thread's state so that it continues doing something else. 190 <p> 191 <dt> <strong>thread_resume</strong> 192 <dd> 193 Let the thread start running from its new state. 194</dl> 195Returning a value other than KERN_SUCCESS insures that no reply message 196will be sent. 197sent. (Actually, the kernel uses a send once right to send the exception 198message, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.) 199The thread can always be destroyed with <strong>thread_terminate</strong>. 200<p> 201A thread can have two exception ports active for it: its thread type specific exception 202port and the task type specific exception port. The kernel will try sending 203an exception message to both ports looking for a reply message with a 204return value of KERN_SUCCESS. The kernel tries the thread specific port first, 205then the task specific port. If the return value from the first exception message 206the kernel sends has a return value of KERN_SUCCESS, the thread continues 207(with a possibly modified state). If the return value is not KERN_SUCCESS, 208the kernel tries the second port. If that return value is KERN_SUCCESS, the 209thread continues; otherwise, the thread is terminated. 210<p> 211To get the effect of a non-success return value, the server interface should return 212MIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong> 213to destroy the kernel's request (as opposed to sending a reply with a 214KERN_SUCCESS value). 215 216<h3>RETURN VALUES</h3> 217<p> 218A return value of KERN_SUCCESS indicates that the thread is to continue 219from the point of exception. A return value of MIG_NO_REPLY indicates that 220the exception was handled directly and the thread was restarted or terminated by 221the exception handler. A return value of MIG_DESTROY_REQUEST causes 222the kernel to try another exception handler (or terminate the thread). Any other 223value will cause 224<strong>mach_msg_server</strong> to remove the task and thread port references. 225 226<h3>RELATED INFORMATION</h3> 227<p> 228Functions: 229<a href="exc_server.html"><strong>exc_server</strong></a>, 230<a href="thread_abort.html"><strong>thread_abort</strong></a>, 231<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>, 232<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>, 233<a href="thread_get_state.html"><strong>thread_get_state</strong></a>, 234<a href="thread_resume.html"><strong>thread_resume</strong></a>, 235<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>, 236<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>, 237<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>, 238<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>, 239<a href="thread_set_state.html"><strong>thread_set_state</strong></a>, 240<a href="thread_suspend.html"><strong>thread_suspend</strong></a>, 241<a href="thread_terminate.html"><strong>thread_terminate</strong></a>. 242