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

<h2>mach_ports_register</h2>\r<hr>\r<p>\r<strong>Function</strong> - Register an array of well-known ports on behalf of the target task.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   mach_ports_register</strong>\r                <strong>(task_t</strong>                             <var>target_task</var>,\r                 <strong>mach_port_array_t</strong>                <var>init_port_set</var>,\r                 <strong>target_task</strong>              <var>init_port_array_count</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>target_task</var> \r<dd>\r[in task send right]\rThe task for which the ports are to be registered.\r<p>\r<dt> <var>init_port_set</var> \r<dd>\r[in pointer to array of registered send rights]\rThe array of ports to\rregister.\r<p>\r<dt> <var>init_port_array_count</var> \r<dd>\r[in scalar]\rThe number of ports in the array.  Note that while this is a \rvariable, the kernel accepts only a limited number of ports.  The\rmaximum number of ports is defined by the global constant\r<strong>MACH_PORTS_SLOTS_USED</strong>.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>mach_ports_register</strong> function registers an array\rof well-known system \rports for the specified task.  The task holds only send rights\rfor the registered \rports.  The valid well-known system ports are:\r<ul>\r<li>\rThe port for the Name Server\r<li>\rThe port for the Environment Manager\r<li>\rThe port for the Service server\r</ul>\r<p>\rEach port must be placed in a specific slot in the array.  The slot numbers are\rdefined (in <strong>mach.h</strong>) by the global constants <strong>NAME_SERVER_SLOT</strong>,\r<strong>ENVIRONMENT_SLOT</strong>, and <strong>SERVICE_SLOT</strong>.\r<p>\rA task can retrieve the currently registered ports by using the\r<strong>mach_ports_lookup</strong> function.\r<h3>NOTES</h3>\r<p>\rWhen a new task is created (with <strong>task_create</strong>), \rthe child task can inherit the\rparent's registered ports.  Note that child tasks do not automatically\racquire rights \rto these ports.  They must use <strong>mach_ports_lookup</strong> to\rget them.  It is intended \rthat port registration be used only for task initialization, and then only by\rrun-time support modules.\r<p>\rA parent task has three choices when passing registered ports to child tasks:\r<ul>\r<li>\rThe parent task can do nothing.  In this case, all child tasks\rinherit access to \rthe same ports that the parent has.\r<li>\rThe parent task can use <strong>mach_ports_register</strong> to modify\rits set of registered \rports before creating child tasks.  In this case, the child tasks get access \rto the \rmodified set of ports.  After creating its child tasks. the parent can use \r<strong>mach_ports_register</strong> again to reset its registered ports.\r<li>\rThe parent task can first create a specific child task and then use\r<strong>mach_ports_register</strong> to modify the child's inherited\rset of ports, before starting \rthe child's thread(s).  The parent must specify the child's task port, rather \rthan its own, on the call to <strong>mach_ports_register</strong>. \r</ul>\r<p>\rTasks other than the Name Server and the Environment Manager \rshould not need access to the Service port.  The Name Server port is \rthe same for all tasks on a given machine.  The Environment port\ris the only port \rlikely to have different values for different tasks.\r<p>\rRegistered ports are restricted to those ports that are used by the run-time\rsystem to initialize a task.  A parent task can pass other ports\rto its child tasks \rthrough:\r<ul>\r<li>\rAn initial message (see <strong>mach_msg</strong>).\r<li>\rThe Name Server, for public ports.\r<li>\rThe Environment Manager, for private ports.\r<li>\rThe task bootstrap port (see <strong>task_get_special_port</strong>).\r</ul>\r<h3>RETURN VALUES</h3>\r<p>\rOnly generic errors apply.\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,\r<a href="mach_ports_lookup.html"><strong>mach_ports_lookup</strong></a>.\r