1<h2>mach_port_allocate_subsystem</h2>
2<hr>
3<p>
4<strong>Function</strong> - Create a port right associated with the caller-specified subsystem.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_port_allocate_subsystem</strong>
8                <strong>(ipc_space_t</strong>                               <var>task</var>,
9                 <strong>subsystem_t</strong>                             <var>subsys</var>,
10                 <strong>mach_port_name_t</strong>              <var>mach_port_name_t</var><strong>);</strong>
11</pre>
12<h3>PARAMETERS</h3>
13<dl>
14<p>
15<dt> <var>task</var>
16<dd>
17[in task send right] The task acquiring the port right.
18<p>
19<dt> <var>subsys</var>
20<dd>
21[in scalar] The port right naming the subsystem the newly created port 
22is to be associated with.
23<p>
24<dt> <var>name</var>
25<dd>
26[out scalar] The task's name for the port right. This can be any name 
27that wasn't in use.
28</dl>
29<h3>DESCRIPTION</h3>
30<p>
31The <strong>mach_port_allocate_subsystem</strong> function creates a new right
32and associates it
33with the specifed subsystem (specified via the <var>subsys</var> parameter)
34previously registered via a call to the
35<strong>mach_subsystem_create</strong> interface.
36The new right's name is returned in the <var>name</var> parameter. The
37association of this port with the subsystem is immutable for the
38life of the port.
39<p>
40Any RPC targeted at the new port will cause the kernel glue-code
41to locate the server function address and argument signature in the
42associated subsystem.
43<h3>NOTES</h3>
44<p>
45This interface is machine word length specific because of the port
46name parameter.
47<h3>RETURN VALUES</h3>
48<dl>
49<p>
50<dt> <strong>KERN_SUCCESS</strong>
51<dd>
52The right is allocated.
53<p>
54<dt> <strong>KERN_INVALID_TASK</strong>
55<dd>
56The space is null.
57<p>
58<dt> <strong>KERN_INVALID_TASK</strong>
59<dd>
60The space is dead.
61<p>
62<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
63<dd>
64Couldn't allocate memory.
65<p>
66<dt> <strong>KERN_NO_SPACE</strong>
67<dd>
68No room in space for another right.
69</dl>
70<h3>RELATED INFORMATION</h3>
71<p>
72Functions:
73<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>,
74<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>.
75