osfmk/man/thread_set_exception_ports.html

   1 <h2>thread_set_exception_ports</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Set exception ports for a thread.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_set_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><strong>);</strong>
  13 </pre>
  14 <h3>PARAMETERS</h3>
  15 <dl>
  16 <p>
  17 <dt> <var>thread</var>
  18 <dd>
  19 [in thread send right]
  20 The thread for which to set the ports.
  21 <p>
  22 <dt> <var>exception_types</var>
  23 <dd>
  24 [in scalar]
  25 A flag word indicating the types of exceptions for which the
  26 exception port applies:
  27 <dl>
  28 <p>
  29 <dt> <strong>EXC_MASK_BAD_ACCESS</strong>
  30 <dd>
  31 Could not access memory.
  32 <p>
  33 <dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
  34 <dd>
  35 Instruction failed.  Illegal or undefined instruction or operand.
  36 <p>
  37 <dt> <strong>EXC_MASK_ARITHMETIC</strong>
  38 <dd>
  39 Arithmetic exception.
  40 <p>
  41 <dt> <strong>EXC_MASK_EMULATION</strong>
  42 <dd>
  43 Emulation instruction.  Emulation support instruction
  44 encountered.
  45 <p>
  46 <dt> <strong>EXC_MASK_SOFTWARE</strong>
  47 <dd>
  48 Software generated exception.
  49 <p>
  50 <dt> <strong>EXC_MASK_BREAKPOINT</strong>
  51 <dd>
  52 Trace, breakpoint, etc.
  53 <p>
  54 <dt> <strong>EXC_MASK_SYSCALL</strong>
  55 <dd>
  56 System call requested.
  57 <p>
  58 <dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
  59 <dd>
  60 System call with a number in the Mach call range requested.
  61 </dl>
  62 <p>
  63 <dt> <var>exception_port</var>
  64 <dd>
  65 [in exception send right]
  66 The exception port for all selected exception
  67 types.
  68 <p>
  69 <dt> <var>behavior</var>
  70 <dd>
  71 [in scalar]
  72 The type of exception message to be sent.  Defined types are:
  73 <dl>
  74 <p>
  75 <dt> <strong>EXCEPTION_DEFAULT</strong>
  76 <dd>
  77 Send a <strong>catch_exception_raise</strong> message including the thread
  78 identity.
  79 <p>
  80 <dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
  81 <dd>
  82 Send a <strong>catch_exception_raise</strong> message including the thread
  83 identity.  Mark the exception port (and associated exceptions)
  84 as protected.
  85 <p>
  86 <dt> <strong>EXCEPTION_STATE</strong>
  87 <dd>
  88 Send a <strong>catch_exception_raise_state</strong> message including the
  89 thread state.
  90 <p>
  91 <dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
  92 <dd>
  93 Send a <strong>catch_exception_raise_state</strong> message including the
  94 thread state.  Mark the exception port (and associated
  95 exceptions) as protected.
  96 <p>
  97 <dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
  98 <dd>
  99 Send a <strong>catch_exception_raise_state_identity</strong> message
 100 including the thread identity and state.
 101 <p>
 102 <dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
 103 <dd>
 104 Send a <strong>catch_exception_raise_state_identity</strong> message
 105 including the thread identity and state.  Mark the exception port
 106 (and associated exceptions) as protected.
 107 </dl>
 108 <p>
 109 <dt> <var>flavor</var>
 110 <dd>
 111 [in scalar]
 112 The type of state to be sent with the exception message.
 113 These types are defined in \*L<mach/thread_states.h>\*O.
 114 </dl>
 115 <h3>DESCRIPTION</h3>
 116 <p>
 117 The <strong>thread_set_exception_ports</strong> function sets a specified
 118 set of exception
 119 ports belonging to <var>thread</var>.
 120 <h3>NOTES</h3>
 121 <p>
 122 If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
 123 the host name port, Mach kernel traps are executed by the kernel as expected;
 124 any other value causes the attempted execution of these system call numbers to
 125 be considered an exception.
 126 <p>
 127 A "protected" exception port is one which cannot be fetched and for which
 128 exception processing cannot be aborted (<strong>thread_abort</strong>).
 129 <h3>RETURN VALUES</h3>
 130 <p>
 131 Only generic errors apply.
 132 <h3>RELATED INFORMATION</h3>
 133 <p>
 134 Functions:
 135 <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
 136 <a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
 137 <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
 138 <a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
 139 <a href="thread_create.html"><strong>thread_create</strong></a>,
 140 <a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
 141 <a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
 142 <a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
 143 <a href="thread_abort.html"><strong>thread_abort</strong></a>.