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