osfmk/man/thread_get_exception_ports.html

   1 <h2>thread_get_exception_ports</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Return a send right to an exception port.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_get_exception_ports</strong>
   8                 <strong>(thread_act_t</strong>                            <var>thread</var>,
   9                  <strong>exception_mask_t</strong>               <var>exception_types</var>,
  10                  <strong>exception_mask_array_t</strong>     <var>old_exception_masks</var>,
  11                  <strong>old_exception_masks</strong>        <var>old_exception_count</var>,
  12                  <strong>exception_port_array_t</strong>     <var>old_exception_ports</var>,
  13                  <strong>exception_behavior_array_t</strong>       <var>old_behaviors</var>,
  14                  <strong>exception_flavor_array_t</strong>           <var>old_flavors</var><strong>);</strong>
  15 </pre>
  16 <h3>PARAMETERS</h3>
  17 <dl>
  18 <p>
  19 <dt> <var>thread</var>
  20 <dd>
  21 [in thread send right]
  22 The thread for which to return the exception
  23 ports.
  24 <p>
  25 <dt> <var>exception_types</var>
  26 <dd>
  27 [in scalar]
  28 A flag word indicating the types of exceptions for which the
  29 exception ports are desired:
  30 <dl>
  31 <p>
  32 <dt> <strong>EXC_MASK_BAD_ACCESS</strong>
  33 <dd>
  34 Could not access memory.
  35 <p>
  36 <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
  37 <dd>
  38 Instruction failed.  Illegal or undefined instruction or operand.
  39 <p>
  40 <dt> <strong>EXC_MASK_ARITHMETIC</strong>
  41 <dd>
  42 Arithmetic exception.
  43 <p>
  44 <dt> <strong>EXC_MASK_EMULATION</strong>
  45 <dd>
  46 Emulation instruction.  Emulation support instruction
  47 encountered.
  48 <p>
  49 <dt> <strong>EXC_MASK_SOFTWARE</strong>
  50 <dd>
  51 Software generated exception.
  52 <p>
  53 <dt> <strong>EXC_MASK_BREAKPOINT</strong>
  54 <dd>
  55 Trace, breakpoint, etc.
  56 <p>
  57 <dt> <strong>EXC_MASK_SYSCALL</strong>
  58 <dd>
  59 System call requested.
  60 <p>
  61 <dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
  62 <dd>
  63 System call with a number in the Mach call range requested.
  64 </dl>
  65 <p>
  66 <dt> <var>old_exception_masks</var>
  67 <dd>
  68 [out array of <var>exception_mask_t</var>]
  69 An array, each element being a mask
  70 specifying for which exception types the corresponding element of the
  71 other arrays apply.
  72 <p>
  73 <dt> <var>old_exception_count</var>
  74 <dd>
  75 [pointer to in/out scalar]
  76 On input, the maximum size of the array
  77 buffers; on output, the number of returned <exception type mask,
  78 exception port, behavior, flavor> sets returned.
  79 <p>
  80 <dt> <var>old_exception_ports</var>
  81 <dd>
  82 [out array of exception send rights]
  83 The returned exception ports.
  84 <p>
  85 <dt> <var>old_behaviors</var>
  86 <dd>
  87 [out array of <var>exception_behavior_t</var>]
  88 The type of exception message to
  89 be sent.  Defined types are:
  90 <dl>
  91 <p>
  92 <dt> <strong>EXCEPTION_DEFAULT</strong>
  93 <dd>
  94 Send a <strong>catch_exception_raise</strong> message including the thread
  95 identity.
  96 <p>
  97 <dt> <strong>EXCEPTION_STATE</strong>
  98 <dd>
  99 Send a <strong>catch_exception_raise_state</strong> message including the
 100 thread state.
 101 <p>
 102 <dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
 103 <dd>
 104 Send a <strong>catch_exception_raise_state_identity</strong> message
 105 including the thread identity and state.
 106 </dl>
 107 <p>
 108 <dt> <var>old_flavors</var>
 109 <dd>
 110 [out array of <var>thread_state_flavor_t</var>]
 111 The type of state to be sent with
 112 the exception message.  These types are defined in \*L<mach/thread_states.h>\*O.
 113 </dl>
 114 <h3>DESCRIPTION</h3>
 115 <p>
 116 The <strong>thread_get_exception_ports</strong> function returns send
 117 rights for a specified
 118 set of exception ports belonging to <var>thread</var>.  The call returns
 119 a set of quadruples
 120 <exception type mask, exception port, behavior, flavor> for each unique set of
 121 <exception port, behavior, flavor> in effect for the thread where
 122 the exception
 123 type mask indicates for which exception types the other values apply.
 124 <h3>RETURN VALUES</h3>
 125 <dl>
 126 <p>
 127 <dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
 128 <dd>
 129 One of the requested exception ports is protected and cannot be returned.
 130 </dl>
 131 <h3>RELATED INFORMATION</h3>
 132 <p>
 133 Functions:
 134 <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
 135 <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
 136 <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
 137 <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
 138 <a href="thread_create.html"><strong>thread_create</strong></a>,
 139 <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
 140 <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
 141 <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>.