osfmk/man/task_swap_exception_ports.html

   1 <h2>task_swap_exception_ports</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Set target task's exception ports, returning the previous exception ports.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   task_swap_exception_ports</strong>
   8                 <strong>(task_t</strong>                                    <var>task</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>task</var>
  23 <dd>
  24 [in task send right]
  25 The task 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 <p>
  67 <dt> <strong>EXC_MASK_RPC_ALERT </strong>
  68 <dd>
  69 Exceptional condition encountered during execution of RPC.
  70 </dl>
  71 <p>
  72 <dt> <var>exception_port</var>
  73 <dd>
  74 [in exception send right]
  75 The exception port for all selected exception
  76 types.
  77 <p>
  78 <dt> <var>behavior</var>
  79 <dd>
  80 [in scalar]
  81 The type of exception message to be sent.  Defined types are:
  82 <dl>
  83 <p>
  84 <dt> <strong>EXCEPTION_DEFAULT</strong>
  85 <dd>
  86 Send a <strong>catch_exception_raise</strong> message including the thread
  87 identity.
  88 <p>
  89 <dt> <strong>EXCEPTION_STATE</strong>
  90 <dd>
  91 Send a <strong>catch_exception_raise_state</strong> message including the
  92 thread state.
  93 <p>
  94 <dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
  95 <dd>
  96 Send a <strong>catch_exception_raise_state</strong> message including the
  97 thread state.  Mark the exception port (and associated
  98 exceptions) as protected.
  99 <p>
 100 <dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
 101 <dd>
 102 Send a <strong>catch_exception_raise_state_identity</strong> message
 103 including the thread identity and state.
 104 <p>
 105 <dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
 106 <dd>
 107 Send a <strong>catch_exception_raise_state_identity</strong> message
 108 including the thread identity and state.  Mark the exception port
 109 (and associated exceptions) as protected.
 110 </dl>
 111 <p>
 112 <dt> <var>flavor</var>
 113 <dd>
 114 [in scalar]
 115 The type of state to be sent with the exception message.
 116 These types are defined in <strong>&ltmach/thread_states.h&gt</strong>.
 117 <p>
 118 <dt> <var>old_exception_masks</var>
 119 <dd>
 120 [out array of <var>exception_mask_t</var>]
 121 An array, each element being a mask
 122 specifying for which exception types the corresponding element of the
 123 other arrays apply.
 124 <p>
 125 <dt> <var>old_exception_count</var>
 126 <dd>
 127 [pointer to in/out scalar]
 128 On input, the maximum size of the array
 129 buffers; on output, the number of returned <exception type mask,
 130 exception port, behavior, flavor> sets returned.
 131 <p>
 132 <dt> <var>old_exception_ports</var>
 133 <dd>
 134 [out array of exception send rights]
 135 The returned exception ports.
 136 <p>
 137 <dt> <var>old_behaviors</var>
 138 <dd>
 139 [out array of <var>exception_behavior_t</var>]
 140 The type of exception message to
 141 be sent as with <var>behavior</var>.
 142 <p>
 143 <dt> <var>old_flavors</var>
 144 <dd>
 145 [out array of <var>thread_state_flavor_t</var>]
 146 The type of state to be sent with
 147 the exception message.  These types are defined in  <strong>&ltmach/thread_states.h&gt</strong>.
 148 </dl>
 149 <h3>DESCRIPTION</h3>
 150 <p>
 151 The <strong>task_swap_exception_ports</strong> function sets a specified
 152 set of exception
 153 ports belonging to <var>task</var>, returning the old set.  A task exception
 154 port is used when
 155 a thread specific exception port returns a non-success reply.
 156 <h3>NOTES</h3>
 157 <p>
 158 If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
 159 the host name port, Mach kernel traps are executed by the kernel as expected;
 160 any other value causes the attempted execution of these system call numbers to
 161 be considered an exception.
 162 <h3>RETURN VALUES</h3>
 163 <p>
 164 Only generic errors apply.
 165 <h3>RELATED INFORMATION</h3>
 166 <p>
 167 Functions:
 168 <a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
 169 <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
 170 <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
 171 <a href="thread_create.html"><strong>thread_create</strong></a>,
 172 <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
 173 <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
 174 <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
 175 <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
 176 <a href="thread_abort.html"><strong>thread_abort</strong></a>.