osfmk/man/TS_exception_ports.html

   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]
  25 The thread for which to set the ports.
  26 <p>
  27 <dt> <var>exception_types</var>
  28 <dd>
  29 [in scalar]
  30 A flag word indicating the types of exceptions for which the
  31 exception port applies:
  32 <dl>
  33 <p>
  34 <dt> <strong>EXC_MASK_BAD_ACCESS</strong>
  35 <dd>
  36 Could not access memory.
  37 <p>
  38 <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
  39 <dd>
  40 Instruction failed.  Illegal or undefined instruction or operand.
  41 <p>
  42 <dt> <strong>EXC_MASK_ARITHMETIC</strong>
  43 <dd>
  44 Arithmetic exception
  45 <p>
  46 <dt> <strong>EXC_MASK_EMULATION</strong>
  47 <dd>
  48 Emulation instruction.  Emulation support instruction
  49 encountered.
  50 <p>
  51 <dt> <strong>EXC_MASK_SOFTWARE</strong>
  52 <dd>
  53 Software generated exception.
  54 <p>
  55 <dt> <strong>EXC_MASK_BREAKPOINT</strong>
  56 <dd>
  57 Trace, breakpoint, etc.
  58 <p>
  59 <dt> <strong>EXC_MASK_SYSCALL</strong>
  60 <dd>
  61 System call requested.
  62 <p>
  63 <dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
  64 <dd>
  65 System 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]
  71 The exception port for all selected exception
  72 types.
  73 <p>
  74 <dt> <var>behavior</var>
  75 <dd>
  76 [in scalar]
  77 Control of the behavior of the exception processing.  Defined
  78 types are:
  79 <dl>
  80 <p>
  81 <dt> <strong>EXCEPTION_DEFAULT</strong>
  82 <dd>
  83 Send a <strong>catch_exception_raise</strong> message including the thread
  84 identity.
  85 <p>
  86 <dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
  87 <dd>
  88 Send a <strong>catch_exception_raise</strong> message including the thread
  89 identity.  Mark the exception port (and associated exceptions)
  90 as protected.
  91 <p>
  92 <dt> <strong>EXCEPTION_STATE</strong>
  93 <dd>
  94 Send a <strong>catch_exception_raise_state</strong> message including the
  95 thread state.
  96 <p>
  97 <dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
  98 <dd>
  99 Send a <strong>catch_exception_raise_state</strong> message including the
 100 thread state.  Mark the exception port (and associated
 101 exceptions) as protected.
 102 <p>
 103 <dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
 104 <dd>
 105 Send a <strong>catch_exception_raise_state_identity</strong> message
 106 including the thread identity and state.
 107 <p>
 108 <dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
 109 <dd>
 110 Send a <strong>catch_exception_raise_state_identity</strong> message
 111 including 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]
 118 The type of state to be sent with the exception message.
 119 These 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>]
 124 An array, each element being a mask
 125 specifying for which exception types the corresponding element of the
 126 other arrays apply.
 127 <p>
 128 <dt> <var>old_exception_count</var>
 129 <dd>
 130 [pointer to in/out scalar]
 131 On input, the maximum size of the array
 132 buffers; on output, the number of returned <exception type mask,
 133 exception port, behavior, flavor> sets returned.
 134 <p>
 135 <dt> <var>old_exception_ports</var>
 136 <dd>
 137 [out array of exception send rights]
 138 The returned exception ports.
 139 <p>
 140 <dt> <var>old_behaviors</var>
 141 <dd>
 142 [out array of <var>exception_behavior_t</var>]
 143 The type of exception message to
 144 be 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>]
 149 The type of state to be sent with
 150 the exception message.  These types are defined in
 151 \*L<mach/thread_states.h>\*O.
 152 </dl>
 153 <h3>DESCRIPTION</h3>
 154 <p>
 155 The <strong>thread_swap_exception_ports</strong> function sets a specified
 156 set of exception
 157 ports belonging to <var>thread</var>, returning the old set.
 158 <h3>NOTES</h3>
 159 <p>
 160 If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
 161 the host name port, Mach kernel traps are executed by the kernel as expected;
 162 any other value causes the attempted execution of these system call numbers to
 163 be considered an exception.
 164 <p>
 165 A "protected" exception port is one which cannot be fetched and for which
 166 exception 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>
 172 One of the requested exception ports is protected and cannot be returned.
 173 </dl>
 174 <h3>RELATED INFORMATION</h3>
 175 <p>
 176 Functions:
 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>.