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

<h2>thread_suspend</h2>\r<hr>\r<p>\r<strong>Function</strong> - Suspend a thread.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   thread_suspend</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 suspended.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>thread_suspend</strong> function increments the suspend\rcount for <var>target_thread</var> \rand prevents the thread from executing any more user-level instructions.\r<p>\rIn this context, a user-level instruction can be either a machine instruction\rexecuted in user mode or a system trap instruction, including\ra page fault.  If a \rthread is currently executing within a system trap, the kernel\rcode may continue \rto execute until it reaches the system return code or it may\rsuspend within the \rkernel code.  In either case, the system trap returns when the thread resumes. \r<p>\rTo resume a suspended thread, use <strong>thread_resume</strong>.  If\rthe suspend count is \rgreater than one, <strong>thread_resume</strong> must be repeated that\rnumber of times.\r<h3>CAUTIONS</h3>\r<p>\rUnpredictable results may occur if a program suspends a thread and alters its \ruser state so that its direction is changed upon resuming.  Note that the\r<strong>thread_abort</strong> function allows a system call to be aborted\ronly if it is progressing in a \rpredictable way.\r<h3>RETURN VALUES</h3>\r<p>\rOnly generic errors apply.\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="task_resume.html"><strong>task_resume</strong></a>,\r<a href="task_suspend.html"><strong>task_suspend</strong></a>,\r<a href="thread_abort.html"><strong>thread_abort</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_resume.html"><strong>thread_resume</strong></a>,\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.\r