osfmk/man/MP_allocate_subsystem.html

   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
  22 is 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
  27 that wasn't in use.
  28 </dl>
  29 <h3>DESCRIPTION</h3>
  30 <p>
  31 The <strong>mach_port_allocate_subsystem</strong> function creates a new right
  32 and associates it
  33 with the specifed subsystem (specified via the <var>subsys</var> parameter)
  34 previously registered via a call to the
  35 <strong>mach_subsystem_create</strong> interface.
  36 The new right's name is returned in the <var>name</var> parameter. The
  37 association of this port with the subsystem is immutable for the
  38 life of the port.
  39 <p>
  40 Any RPC targeted at the new port will cause the kernel glue-code
  41 to locate the server function address and argument signature in the
  42 associated subsystem.
  43 <h3>NOTES</h3>
  44 <p>
  45 This interface is machine word length specific because of the port
  46 name parameter.
  47 <h3>RETURN VALUES</h3>
  48 <dl>
  49 <p>
  50 <dt> <strong>KERN_SUCCESS</strong>
  51 <dd>
  52 The right is allocated.
  53 <p>
  54 <dt> <strong>KERN_INVALID_TASK</strong>
  55 <dd>
  56 The space is null.
  57 <p>
  58 <dt> <strong>KERN_INVALID_TASK</strong>
  59 <dd>
  60 The space is dead.
  61 <p>
  62 <dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
  63 <dd>
  64 Couldn't allocate memory.
  65 <p>
  66 <dt> <strong>KERN_NO_SPACE</strong>
  67 <dd>
  68 No room in space for another right.
  69 </dl>
  70 <h3>RELATED INFORMATION</h3>
  71 <p>
  72 Functions:
  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>.