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