1<h2>mach_subsystem_create</h2>
2<hr>
3<p>
4<strong>Function</strong> - Register information about an RPC subsystem.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   mach_subsystem_create</strong>
8                <strong>(task_t</strong>                             <var>target_task</var>,
9                 <strong>user_subsystem_t</strong>                   <var>user_subsys</var>,
10                 <strong>mach_msg_type_number_t</strong>          <var>user_subsysCnt</var>,
11                 <strong>subsystem_t</strong>                        <var>subsystem_t</var><strong>);</strong>
12</pre>
13<h3>PARAMETERS</h3>
14<dl>
15<p>
16<dt> <var>target_task</var>
17<dd>
18The task for which the subsystem is registered; normally the calling 
19task, but not necessarily.
20<p>
21<dt> <var>user_subsys</var>
22<dd>
23The MIG-generated data structure describing the exported routines and 
24their input/output characteristics (e.g. arguments and return values).
25<p>
26<dt> <var>user_subsysCnt</var>
27<dd>
28The size of the user_subsys data structure argument, in bytes.
29<p>
30<dt> <var>subsys</var>
31<dd>
32The port returned that names the registered subsystem.
33</dl>
34<h3>DESCRIPTION</h3>
35<p>
36The <strong>mach_subsystem_create</strong> function is used by a server to register
37information about an RPC subsystem with the kernel.
38MIG automatically generates, in the server source file, a
39<strong>user_subsystem_t</strong> data structure that is appropriate for registering
40the subsystem. This data structure includes a per-routine array that
41specifies:
42<ul>
43<li>
44The address of the server function that performs the work.
45<li>
46The address of the MIG-generated server-side marshalling stub, to be 
47used with <strong>mach_msg</strong>.
48<li>
49The argument signature (i.e. NDR-style argument format) of the
50routine.
51</ul>
52<p>
53Upon successful completion, <strong>mach_subsystem_create</strong> returns,
54via the <var>subsys</var> parameter, a port naming the registered subsystem.
55<p>
56Each port on which the server is to receive short-circuited RPC's (or
57a <strong>mach_rpc</strong> call) must be associated with a registered subsystem, by
58calling <strong>mach_port_allocate_subsystem</strong>.
59<h3>RETURN VALUES</h3>
60<dl>
61<p>
62<dt> <strong>KERN_INVALD_ADDRESS</strong>
63<dd>
64One or more of the addresses in the range specified by the subsystem
65address and size are not valid addresses in the caller, or some of the
66internal pointers in the subsystem do not point to places within the
67address range (all of the data of the subsystem is required to be
68contiguous, even the parts that are pointed to by other parts).
69<p>
70<dt> <strong>KERN_INVALID_ARGUMENT</strong>
71<dd>
72The port name specified by <var>target_task</var> is not a send right naming a task,
73or the subsystem size is too small to be valid.
74<p>
75<dt> <strong>KERN_INVALID_TASK</strong>
76<dd>
77The target task is dead.
78<p>
79<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
80<dd>
81The kernel cannot allocate the subsystem due to insufficient available 
82memory.
83</dl>
84<h3>RELATED INFORMATION</h3>
85<p>
86Functions:
87<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,
88<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>.
89