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

<h2>mach_port_allocate_subsystem</h2>\r<hr>\r<p>\r<strong>Function</strong> - Create a port right associated with the caller-specified subsystem.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   mach_port_allocate_subsystem</strong>\r                <strong>(ipc_space_t</strong>                               <var>task</var>,\r                 <strong>subsystem_t</strong>                             <var>subsys</var>,\r                 <strong>mach_port_name_t</strong>              <var>mach_port_name_t</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>task</var>\r<dd>\r[in task send right] The task acquiring the port right.\r<p>\r<dt> <var>subsys</var>\r<dd>\r[in scalar] The port right naming the subsystem the newly created port \ris to be associated with.\r<p>\r<dt> <var>name</var>\r<dd>\r[out scalar] The task's name for the port right. This can be any name \rthat wasn't in use.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>mach_port_allocate_subsystem</strong> function creates a new right\rand associates it\rwith the specifed subsystem (specified via the <var>subsys</var> parameter)\rpreviously registered via a call to the\r<strong>mach_subsystem_create</strong> interface.\rThe new right's name is returned in the <var>name</var> parameter. The\rassociation of this port with the subsystem is immutable for the\rlife of the port.\r<p>\rAny RPC targeted at the new port will cause the kernel glue-code\rto locate the server function address and argument signature in the\rassociated subsystem.\r<h3>NOTES</h3>\r<p>\rThis interface is machine word length specific because of the port\rname parameter.\r<h3>RETURN VALUES</h3>\r<dl>\r<p>\r<dt> <strong>KERN_SUCCESS</strong>\r<dd>\rThe right is allocated.\r<p>\r<dt> <strong>KERN_INVALID_TASK</strong>\r<dd>\rThe space is null.\r<p>\r<dt> <strong>KERN_INVALID_TASK</strong>\r<dd>\rThe space is dead.\r<p>\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>\r<dd>\rCouldn't allocate memory.\r<p>\r<dt> <strong>KERN_NO_SPACE</strong>\r<dd>\rNo room in space for another right.\r</dl>\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>,\r<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>.\r