osfmk/man/thread_abort.html

   1 <h2>thread_abort</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Abort a thread.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_abort</strong>
   8                 <strong>(thread_act_t</strong>                     <var>target_thread</var><strong>);</strong>
   9 </pre>
  10 <h3>PARAMETERS</h3>
  11 <dl>
  12 <p>
  13 <dt> <var>target_thread</var>
  14 <dd>
  15 [in thread send right]
  16 The thread to be aborted.
  17 </dl>
  18 <h3>DESCRIPTION</h3>
  19 <p>
  20 The <strong>thread_abort</strong> function aborts page faults and any
  21 message primitive calls
  22 in use by <var>target_thread</var>.  Scheduling depressions and clock sleeps are also
  23 aborted.  The call returns a code indicating that it was interrupted.
  24 The call is
  25 interrupted even if the thread (or the task containing it) is
  26 suspended.  If it is
  27 suspended, the thread receives the interrupt when it resumes.
  28 <p>
  29 If its state is not modified before it resumes, the thread will
  30 retry an aborted
  31 page fault.  The Mach message trap returns either
  32 <strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending
  33 on whether the send or the
  34 receive side was interrupted.  Note, though, that the Mach message trap is
  35 contained within the <strong>mach_msg</strong> library routine, which,
  36 by default, retries
  37 interrupted message calls.
  38 <p>
  39 The basic purpose of <strong>thread_abort</strong> is to let one thread
  40 cleanly stop another thread (<var>target_thread</var>).
  41 The target thread is stopped in such a manner that its
  42 future execution can be controlled in a predictable way.  When
  43 <strong>thread_abort</strong>
  44 returns, the target thread will appear to have just returned
  45 from the kernel (if it
  46 had been in kernel mode).
  47 <h3>NOTES</h3>
  48 <p>
  49 By way of comparison, the <strong>thread_suspend</strong> function keeps
  50 the target thread
  51 from executing any further instructions at the user level, including
  52 the return
  53 from a system call.  The <strong>thread_get_state</strong> function
  54 returns the thread's user
  55 state, while <strong>thread_set_state</strong> allows modification of the user state.
  56 <p>
  57 A problem occurs if a suspended thread had been executing within a system
  58 call.  In this case, the thread has, not only a user state, but
  59 an associated kernel
  60 state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)
  61 As a result,
  62 when the thread resumes, the system call can return, producing a change in the
  63 user state and, possibly, user memory.
  64 <p>
  65 For a thread executing within a system call, <strong>thread_abort</strong>
  66 aborts the kernel call
  67 from the thread's point of view.  Specifically, it resets the
  68 kernel state so that the
  69 thread will resume execution at the system call return, with the return code
  70 value set to one of the interrupted codes.  The system call itself
  71 may be completed
  72 entirely, aborted entirely or be partially completed, depending on when the
  73 abort is received.  As a result, if the thread's user state has
  74 been modified by
  75 <strong>thread_set_state</strong>, it will not be altered un-predictably
  76 by any unexpected
  77 system call side effects.
  78 <p>
  79 For example, to simulate a POSIX signal, use the following sequence of calls:
  80 <dl>
  81 <dd>
  82 <strong>thread_suspend</strong>\(emTo stop the thread.
  83 <dd>
  84 <strong>thread_abort</strong>\(emTo interrupt any system call in progress
  85 and set the return
  86 value to "interrupted".  Because the thread is already stopped, it will not
  87 return to user code.
  88 <dd>
  89 <strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a
  90 procedure call to the signal handler.
  91 <dd>
  92 <strong>thread_resume</strong>\(emTo resume execution at the signal handler.
  93 If the thread's
  94 stack is set up correctly, the thread can return to the interrupted system call.
  95 Note that the code to push an extra stack frame and change the registers is
  96 highly machine dependent.
  97 </dl>
  98 <h3>CAUTIONS</h3>
  99 <p>
 100 As a rule, do not use <strong>thread_abort</strong> on a non-suspended
 101 thread.  This operation
 102 is very risky because it is difficult to know which system trap, if any, is
 103 executing and whether an interrupt return will result in some
 104 useful action by the
 105 thread.
 106 <p>
 107 <strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page
 108 <strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable
 109 way.  Such problems can be avoided by using <strong>thread_abort_safely</strong>.
 110 <h3>RETURN VALUES</h3>
 111 <dl>
 112 <p>
 113 <dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
 114 <dd>
 115 The thread is processing a protected exception.
 116 </dl>
 117 <h3>RELATED INFORMATION</h3>
 118 <p>
 119 Functions:
 120 <a href="mach_msg.html"><strong>mach_msg</strong></a>,
 121 <a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
 122 <a href="thread_info.html"><strong>thread_info</strong></a>,
 123 <a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
 124 <a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
 125 <a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
 126 <a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>,
 127 <a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>.