osfmk/man/task_get_special_port.html

   1 <h2>task_get_special_port</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Return a send write to the indicated special port.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   task_get_special_port</strong>
   8                 <strong>(task_t</strong>                                    <var>task</var>,
   9                  <strong>int</strong>                                 <var>which_port</var>,
  10                  <strong>task</strong>                              <var>special_port</var><strong>);</strong>
  11
  12
  13 <strong>Macro Forms:</strong>
  14
  15
  16 <strong>kern_return_t   task_get_bootstrap_port</strong>
  17                 <strong>(task_t</strong>                                    <var>task</var>,
  18                  <strong>task</strong>                              <var>special_port</var><strong>);</strong>
  19
  20
  21 <strong>kern_return_t   task_get_kernel_port</strong>
  22                 <strong>(task_t</strong>                                    <var>task</var>,
  23                  <strong>task</strong>                              <var>special_port</var><strong>);</strong>
  24
  25
  26 <strong>kern_return_t   task_get_host_name_port</strong>
  27                 <strong>(task_t</strong>                                    <var>task</var>,
  28                  <strong>task</strong>                              <var>special_port</var><strong>);</strong>
  29 </pre>
  30 <h3>PARAMETERS</h3>
  31 <dl>
  32 <p>
  33 <dt> <var>task</var>
  34 <dd>
  35 [in task send right]
  36 The port for the task for which to return the port's
  37 send right.
  38 <p>
  39 <dt> <var>which_port</var>
  40 <dd>
  41 [in scalar]
  42 The special port for which the send right is requested.  Valid
  43 values are:
  44 <dl>
  45 <p>
  46 <dt> <strong>TASK_KERNEL_PORT</strong>
  47 <dd>
  48 [task-self send right] The port used to control this task.  Used
  49 to send messages that affect the task.  This is the movable task port and
  50 different from the one returned by <strong>mach_task_self</strong> (immovable).
  51 <p>
  52 <dt> <strong>TASK_BOOTSTRAP_PORT</strong>
  53 <dd>
  54 [bootstrap send right] The task's bootstrap port.  Used to send
  55 messages requesting return of other system service ports.
  56 <p>
  57 <dt> <strong>TASK_HOST_NAME_PORT</strong>
  58 <dd>
  59 [host-self send right] The port used to request information of
  60 the containing host.  This is the port returned by
  61 <strong>mach_host_self</strong>.
  62 <p>
  63 <dt> <strong>TASK_WIRED_LEDGER_PORT</strong>
  64 <dd>
  65 [ledger send right] The port naming the source from which
  66 this task draws its wired kernel memory.
  67 <p>
  68 <dt> <strong>TASK_PAGED_LEDGER_PORT</strong>
  69 <dd>
  70 [ledger send right] The port naming the source from which
  71 this task draws its default memory managed memory.
  72 </dl>
  73 <p>
  74 <dt> <var>special_port</var>
  75 <dd>
  76 [out task-special send right]
  77 The returned value for the port.
  78 </dl>
  79 <h3>DESCRIPTION</h3>
  80 <p>
  81 The <strong>task_get_special_port</strong> function returns a send right
  82 for a special port belonging to <var>task</var>.
  83 <p>
  84 If one task has a send right for the kernel port of another task, it can use
  85 the port to perform kernel operations for the other task.  Send rights for a
  86 kernel port normally are held only by the task to which the port belongs,
  87 or by the task's parent task.  Using the <strong>mach_msg</strong> function, however,
  88 any task can pass a send right for its kernel port to another task.
  89 <h3>NOTES</h3>
  90 <p>
  91 The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong>
  92 features associated with this interface.
  93 <h3>RETURN VALUES</h3>
  94 <p>
  95 Only generic errors apply.
  96 <h3>RELATED INFORMATION</h3>
  97 <p>
  98 Functions:
  99 <a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
 100 <a href="task_create.html"><strong>task_create</strong></a>,
 101 <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
 102 <a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
 103 <a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
 104 <a href="mach_host_self.html"><strong>mach_host_self</strong></a>.