osfmk/man/catch_exception_raise.html

   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>
  18 expanded 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>
  33 expanded 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
  53 notification 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
  58 exception.
  59 <p>
  60 <dt> <var>task</var>
  61 <dd>
  62 [in task-self send right] The task self port for the task containing the
  63 thread taking the exception.
  64 <p>
  65 <dt> <var>exception</var>
  66 <dd>
  67 [in scalar] The type of the exception.
  68 The machine independent values raised by all implementations are:
  69      <dl>
  70 <p>
  71 <dt> EXC_BAD_ACCESS
  72 <dd>
  73 Could not access memory. subcode contains the bad memory
  74 address.
  75 <p>
  76 <dt> EXC_BAD_INSTRUCTION
  77 <dd>
  78 Instruction failed. Illegal or undefined instruction or operand.
  79 <p>
  80 <dt> EXC_ARITHMETIC
  81 <dd>
  82 Arithmetic exception; exact nature of exception is in subcode
  83 field.
  84 <p>
  85 <dt> EXC_EMULATION
  86 <dd>
  87 Emulation instruction. Emulation support instruction encountered.
  88 Details in subcode field.
  89 <p>
  90 <dt> EXC_SOFTWARE
  91 <dd>
  92 Software generated exception; exact exception is in subcode
  93 field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000
  94 - 0x1FFFF reserved for OS emulation.
  95 <p>
  96 <dt> EXC_BREAKPOINT
  97 <dd>
  98 Trace, breakpoint, etc. Details in subcode field.
  99 <p>
 100 <dt> EXC_SYSCALL
 101 <dd>
 102 System call requested. Details in subcode field.
 103 <p>
 104 <dt> EXC_MACH_SYSCALL
 105 <dd>
 106 System call with a number in the Mach call range requested.
 107 Details 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
 113 of 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
 122 when the exception port was set. On output, the type of state being
 123 returned.
 124 <p>
 125 <dt> <var>in_state</var>
 126 <dd>
 127 [pointer to in structure] State information of the thread at the time of
 128 the 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
 137 point of the exception. The maximum size of this array is
 138 THREAD_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>
 146 A <strong>catch_exception_raise</strong> function is called by
 147 <strong>exc_server</strong> as the result of a
 148 kernel message indicating that an exception occurred within a thread.
 149 The <var>exception_port</var> parameter specifies the port named via
 150 a previous call to <strong>thread_set_exception_ports</strong> or
 151 <strong>task_set_exception_ports</strong>
 152 as the port that responds when the thread takes an
 153 exception.
 154 <p>
 155 The alternate message forms (the format being selected when the exception port
 156 was set) allow for selected thread state to be included.
 157
 158 <h3>NOTES</h3>
 159 <p>
 160 When an exception occurs in a thread, the thread sends an exception message to
 161 its exception port, blocking in the kernel waiting for the receipt of a reply. It is
 162 assumed that some task is listening
 163 (most likely with <strong>mach_msg_server</strong>) to this
 164 port, using the <strong>exc_server</strong> function
 165 to decode the messages and then call the
 166 linked in <strong>catch_exception_raise</strong>.
 167 It is the job of <strong>catch_exception_raise</strong> to handle
 168 the exception and decide the course of action for thread.
 169      <p>
 170 If the thread should continue from the point of exception,
 171 <strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply
 172 message to be sent to the kernel, which will allow the thread to continue from
 173 the point of the exception.
 174 If some other action should be taken by thread, the following actions should be
 175 performed 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
 184 the thread.
 185                       <p>
 186 <dt> <strong>thread_set_state</strong>
 187      <dd>
 188           (if using the <strong>catch_exception_raise</strong> form). Set the
 189 thread'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>
 195 Returning a value other than KERN_SUCCESS insures that no reply message
 196 will be sent.
 197 sent. (Actually, the kernel uses a send once right to send the exception
 198 message, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.)
 199 The thread can always be destroyed with <strong>thread_terminate</strong>.
 200 <p>
 201 A thread can have two exception ports active for it: its thread type specific exception
 202 port and the task type specific exception port. The kernel will try sending
 203 an exception message to both ports looking for a reply message with a
 204 return value of KERN_SUCCESS. The kernel tries the thread specific port first,
 205 then the task specific port. If the return value from the first exception message
 206 the 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,
 208 the kernel tries the second port. If that return value is KERN_SUCCESS, the
 209 thread continues; otherwise, the thread is terminated.
 210 <p>
 211 To get the effect of a non-success return value, the server interface should return
 212 MIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong>
 213 to destroy the kernel's request (as opposed to sending a reply with a
 214 KERN_SUCCESS value).
 215
 216 <h3>RETURN VALUES</h3>
 217 <p>
 218 A return value of KERN_SUCCESS indicates that the thread is to continue
 219 from the point of exception. A return value of MIG_NO_REPLY indicates that
 220 the exception was handled directly and the thread was restarted or terminated by
 221 the exception handler. A return value of MIG_DESTROY_REQUEST causes
 222 the kernel to try another exception handler (or terminate the thread). Any other
 223 value will cause
 224 <strong>mach_msg_server</strong> to remove the task and thread port references.
 225
 226 <h3>RELATED INFORMATION</h3>
 227 <p>
 228 Functions:
 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>.