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

<h2>thread_get_special_port</h2>\r<hr>\r<p>\r<strong>Function</strong> - Return a send right to the caller-specified special port.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   thread_get_special_port</strong>\r                <strong>(thread_act_t</strong>                            <var>thread</var>,\r                 <strong>int</strong>                                 <var>which_port</var>,\r                 <strong>thread</strong>                            <var>special_port</var><strong>);</strong>\r</pre>\r\r<h4>Macro form:</h4>\r\r<pre>\r<strong>kern_return_t   thread_get_kernel_port</strong>\r                <strong>(thread_act_t</strong>                            <var>thread</var>,\r                 <strong>thread</strong>                            <var>special_port</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>thread</var> \r<dd>\r[in thread send right]\rThe thread for which to return the port's send \rright.\r<p>\r<dt> <var>which_port</var> \r<dd>\r[in scalar]\rThe special port for which the send right is requested.  Valid \rvalues are:\r<dl>\r<p>\r<dt> <strong>THREAD_KERNEL_PORT</strong>\r<dd>\r[thread-self send right] The port used to name the thread. \rUsed to invoke operations that affect the thread.  This is the \rport returned by <strong>mach_thread_self</strong>.\r</dl>\r<p>\r<dt> <var>special_port</var> \r<dd>\r[out thread-special send right]\rThe returned value for the port.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>thread_get_special_port</strong> function returns a send\rright for a special port\rbelonging to <var>thread</var>.\r<p>\rThe thread kernel port is a port for which the kernel holds the\rreceive right.  The \rkernel uses this port to identify the thread.\r<p>\rIf one thread has a send right for the kernel port of another\rthread, it can use the \rport to perform kernel operations for the other thread.  Send\rrights for a kernel \rport normally are held only by the thread to which the port belongs, or by the \rtask that contains the thread.  Using the <strong>mach_msg</strong>\rfunction, however, any \rthread can pass a send right for its kernel port to another thread.\r<h3>RETURN VALUES</h3>\r<p>\rOnly generic errors apply.\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,\r<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,\r<a href="thread_create.html"><strong>thread_create</strong></a>,\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>.\r