osfmk/man/task_get_exception_ports.html

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