osfmk/man/mach_ports_register.html

   1 <h2>mach_ports_register</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Register an array of well-known ports on behalf of the target task.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   mach_ports_register</strong>
   8                 <strong>(task_t</strong>                             <var>target_task</var>,
   9                  <strong>mach_port_array_t</strong>                <var>init_port_set</var>,
  10                  <strong>target_task</strong>              <var>init_port_array_count</var><strong>);</strong>
  11 </pre>
  12 <h3>PARAMETERS</h3>
  13 <dl>
  14 <p>
  15 <dt> <var>target_task</var>
  16 <dd>
  17 [in task send right]
  18 The task for which the ports are to be registered.
  19 <p>
  20 <dt> <var>init_port_set</var>
  21 <dd>
  22 [in pointer to array of registered send rights]
  23 The array of ports to
  24 register.
  25 <p>
  26 <dt> <var>init_port_array_count</var>
  27 <dd>
  28 [in scalar]
  29 The number of ports in the array.  Note that while this is a
  30 variable, the kernel accepts only a limited number of ports.  The
  31 maximum number of ports is defined by the global constant
  32 <strong>MACH_PORTS_SLOTS_USED</strong>.
  33 </dl>
  34 <h3>DESCRIPTION</h3>
  35 <p>
  36 The <strong>mach_ports_register</strong> function registers an array
  37 of well-known system
  38 ports for the specified task.  The task holds only send rights
  39 for the registered
  40 ports.  The valid well-known system ports are:
  41 <ul>
  42 <li>
  43 The port for the Name Server
  44 <li>
  45 The port for the Environment Manager
  46 <li>
  47 The port for the Service server
  48 </ul>
  49 <p>
  50 Each port must be placed in a specific slot in the array.  The slot numbers are
  51 defined (in <strong>mach.h</strong>) by the global constants <strong>NAME_SERVER_SLOT</strong>,
  52 <strong>ENVIRONMENT_SLOT</strong>, and <strong>SERVICE_SLOT</strong>.
  53 <p>
  54 A task can retrieve the currently registered ports by using the
  55 <strong>mach_ports_lookup</strong> function.
  56 <h3>NOTES</h3>
  57 <p>
  58 When a new task is created (with <strong>task_create</strong>),
  59 the child task can inherit the
  60 parent's registered ports.  Note that child tasks do not automatically
  61 acquire rights
  62 to these ports.  They must use <strong>mach_ports_lookup</strong> to
  63 get them.  It is intended
  64 that port registration be used only for task initialization, and then only by
  65 run-time support modules.
  66 <p>
  67 A parent task has three choices when passing registered ports to child tasks:
  68 <ul>
  69 <li>
  70 The parent task can do nothing.  In this case, all child tasks
  71 inherit access to
  72 the same ports that the parent has.
  73 <li>
  74 The parent task can use <strong>mach_ports_register</strong> to modify
  75 its set of registered
  76 ports before creating child tasks.  In this case, the child tasks get access
  77 to the
  78 modified set of ports.  After creating its child tasks. the parent can use
  79 <strong>mach_ports_register</strong> again to reset its registered ports.
  80 <li>
  81 The parent task can first create a specific child task and then use
  82 <strong>mach_ports_register</strong> to modify the child's inherited
  83 set of ports, before starting
  84 the child's thread(s).  The parent must specify the child's task port, rather
  85 than its own, on the call to <strong>mach_ports_register</strong>.
  86 </ul>
  87 <p>
  88 Tasks other than the Name Server and the Environment Manager
  89 should not need access to the Service port.  The Name Server port is
  90 the same for all tasks on a given machine.  The Environment port
  91 is the only port
  92 likely to have different values for different tasks.
  93 <p>
  94 Registered ports are restricted to those ports that are used by the run-time
  95 system to initialize a task.  A parent task can pass other ports
  96 to its child tasks
  97 through:
  98 <ul>
  99 <li>
 100 An initial message (see <strong>mach_msg</strong>).
 101 <li>
 102 The Name Server, for public ports.
 103 <li>
 104 The Environment Manager, for private ports.
 105 <li>
 106 The task bootstrap port (see <strong>task_get_special_port</strong>).
 107 </ul>
 108 <h3>RETURN VALUES</h3>
 109 <p>
 110 Only generic errors apply.
 111 <h3>RELATED INFORMATION</h3>
 112 <p>
 113 Functions:
 114 <a href="mach_msg.html"><strong>mach_msg</strong></a>,
 115 <a href="mach_ports_lookup.html"><strong>mach_ports_lookup</strong></a>.