[apple/xnu.git] / osfmk / man / thread_abort.html

<h2>thread_abort</h2>\r<hr>\r<p>\r<strong>Function</strong> - Abort a thread.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   thread_abort</strong>\r                <strong>(thread_act_t</strong>                     <var>target_thread</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>target_thread</var> \r<dd>\r[in thread send right]\rThe thread to be aborted.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>thread_abort</strong> function aborts page faults and any\rmessage primitive calls \rin use by <var>target_thread</var>.  Scheduling depressions and clock sleeps are also\raborted.  The call returns a code indicating that it was interrupted.\rThe call is\rinterrupted even if the thread (or the task containing it) is\rsuspended.  If it is \rsuspended, the thread receives the interrupt when it resumes.\r<p>\rIf its state is not modified before it resumes, the thread will\rretry an aborted \rpage fault.  The Mach message trap returns either\r<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending\ron whether the send or the\rreceive side was interrupted.  Note, though, that the Mach message trap is \rcontained within the <strong>mach_msg</strong> library routine, which,\rby default, retries\rinterrupted message calls.\r<p>\rThe basic purpose of <strong>thread_abort</strong> is to let one thread\rcleanly stop another thread (<var>target_thread</var>).  \rThe target thread is stopped in such a manner that its\rfuture execution can be controlled in a predictable way.  When\r<strong>thread_abort</strong>\rreturns, the target thread will appear to have just returned\rfrom the kernel (if it \rhad been in kernel mode).\r<h3>NOTES</h3>\r<p>\rBy way of comparison, the <strong>thread_suspend</strong> function keeps\rthe target thread \rfrom executing any further instructions at the user level, including\rthe return \rfrom a system call.  The <strong>thread_get_state</strong> function\rreturns the thread's user \rstate, while <strong>thread_set_state</strong> allows modification of the user state.\r<p>\rA problem occurs if a suspended thread had been executing within a system \rcall.  In this case, the thread has, not only a user state, but\ran associated kernel \rstate. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)\rAs a result, \rwhen the thread resumes, the system call can return, producing a change in the \ruser state and, possibly, user memory.\r<p>\rFor a thread executing within a system call, <strong>thread_abort</strong>\raborts the kernel call \rfrom the thread's point of view.  Specifically, it resets the\rkernel state so that the \rthread will resume execution at the system call return, with the return code\rvalue set to one of the interrupted codes.  The system call itself\rmay be completed \rentirely, aborted entirely or be partially completed, depending on when the \rabort is received.  As a result, if the thread's user state has\rbeen modified by \r<strong>thread_set_state</strong>, it will not be altered un-predictably\rby any unexpected\rsystem call side effects.\r<p>\rFor example, to simulate a POSIX signal, use the following sequence of calls:\r<dl>\r<dd>\r<strong>thread_suspend</strong>\(emTo stop the thread.\r<dd>\r<strong>thread_abort</strong>\(emTo interrupt any system call in progress\rand set the return \rvalue to "interrupted".  Because the thread is already stopped, it will not\rreturn to user code.\r<dd>\r<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a\rprocedure call to the signal handler.\r<dd>\r<strong>thread_resume</strong>\(emTo resume execution at the signal handler.  \rIf the thread's \rstack is set up correctly, the thread can return to the interrupted system call. \rNote that the code to push an extra stack frame and change the registers is \rhighly machine dependent.\r</dl>\r<h3>CAUTIONS</h3>\r<p>\rAs a rule, do not use <strong>thread_abort</strong> on a non-suspended\rthread.  This operation \ris very risky because it is difficult to know which system trap, if any, is\rexecuting and whether an interrupt return will result in some\ruseful action by the \rthread.\r<p>\r<strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page\r<strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable\rway.  Such problems can be avoided by using <strong>thread_abort_safely</strong>.\r<h3>RETURN VALUES</h3>\r<dl>\r<p>\r<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>\r<dd>\rThe thread is processing a protected exception.\r</dl>\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,\r<a href="thread_info.html"><strong>thread_info</strong></a>,\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,\r<a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>,\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>.\r