osfmk/man/thread_get_special_port.html

   1 <h2>thread_get_special_port</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Return a send right to the caller-specified special port.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_get_special_port</strong>
   8                 <strong>(thread_act_t</strong>                            <var>thread</var>,
   9                  <strong>int</strong>                                 <var>which_port</var>,
  10                  <strong>thread</strong>                            <var>special_port</var><strong>);</strong>
  11 </pre>
  12
  13 <h4>Macro form:</h4>
  14
  15 <pre>
  16 <strong>kern_return_t   thread_get_kernel_port</strong>
  17                 <strong>(thread_act_t</strong>                            <var>thread</var>,
  18                  <strong>thread</strong>                            <var>special_port</var><strong>);</strong>
  19 </pre>
  20 <h3>PARAMETERS</h3>
  21 <dl>
  22 <p>
  23 <dt> <var>thread</var>
  24 <dd>
  25 [in thread send right]
  26 The thread for which to return the port's send
  27 right.
  28 <p>
  29 <dt> <var>which_port</var>
  30 <dd>
  31 [in scalar]
  32 The special port for which the send right is requested.  Valid
  33 values are:
  34 <dl>
  35 <p>
  36 <dt> <strong>THREAD_KERNEL_PORT</strong>
  37 <dd>
  38 [thread-self send right] The port used to name the thread.
  39 Used to invoke operations that affect the thread.  This is the
  40 port returned by <strong>mach_thread_self</strong>.
  41 </dl>
  42 <p>
  43 <dt> <var>special_port</var>
  44 <dd>
  45 [out thread-special send right]
  46 The returned value for the port.
  47 </dl>
  48 <h3>DESCRIPTION</h3>
  49 <p>
  50 The <strong>thread_get_special_port</strong> function returns a send
  51 right for a special port
  52 belonging to <var>thread</var>.
  53 <p>
  54 The thread kernel port is a port for which the kernel holds the
  55 receive right.  The
  56 kernel uses this port to identify the thread.
  57 <p>
  58 If one thread has a send right for the kernel port of another
  59 thread, it can use the
  60 port to perform kernel operations for the other thread.  Send
  61 rights for a kernel
  62 port normally are held only by the thread to which the port belongs, or by the
  63 task that contains the thread.  Using the <strong>mach_msg</strong>
  64 function, however, any
  65 thread can pass a send right for its kernel port to another thread.
  66 <h3>RETURN VALUES</h3>
  67 <p>
  68 Only generic errors apply.
  69 <h3>RELATED INFORMATION</h3>
  70 <p>
  71 Functions:
  72 <a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
  73 <a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
  74 <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
  75 <a href="thread_create.html"><strong>thread_create</strong></a>,
  76 <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>.