osfmk/man/mach_port_insert_right.html

   1 <h2>mach_port_insert_right</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Insert the specified port right into the target task.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   mach_port_insert_right</strong>
   8                 <strong>(ipc_space_t</strong>                               <var>task</var>,
   9                  <strong>mach_port_name_t</strong>                          <var>name</var>,
  10                  <strong>mach_port_poly_t</strong>                         <var>right</var>,
  11                  <strong>mach_msg_type_name_t</strong>                <var>right_type</var><strong>);</strong>
  12 </pre>
  13 <h3>PARAMETERS</h3>
  14 <dl>
  15 <p>
  16 <dt> <var>task</var>
  17 <dd>
  18 [in task send right]
  19 The task which gets the caller's right.
  20 <p>
  21 <dt> <var>name</var>
  22 <dd>
  23 [in scalar]
  24 The name by which <var>task</var> will know the right.
  25 <p>
  26 <dt> <var>right</var>
  27 <dd>
  28 [in random right]
  29 The port right.
  30 <p>
  31 <dt> <var>right_type</var>
  32 <dd>
  33 [in scalar]
  34 IPC type of the sent right; e.g.,
  35 <strong>MACH_MSG_TYPE_COPY_SEND</strong> or <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>.
  36 </dl>
  37 <h3>DESCRIPTION</h3>
  38 <p>
  39 The <strong>mach_port_insert_right</strong> function inserts into <var>task</var>
  40 the caller's right for a
  41 port, using a specified name for the right in the target task.
  42 <p>
  43 The specified <var>name</var> can't be one of the reserved values <strong>MACH_PORT_NULL</strong>
  44 or <strong>MACH_PORT_DEAD</strong>.  The <var>right</var> can't be <strong>MACH_PORT_NULL</strong> or
  45 <strong>MACH_PORT_DEAD</strong>.
  46 <p>
  47 The argument <var>right_type</var> specifies a right to be inserted and how that right
  48 should be extracted from the caller.  It should be a value appropriate for
  49 <strong>mach_msg</strong>.
  50 <p>
  51 If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>,
  52 or
  53 <strong>MACH_MSG_TYPE_COPY_SEND</strong>, then a send right is inserted.  If the target
  54 already holds send or receive rights for the port, then <var>name</var>
  55 should denote those rights in the target.  Otherwise, <var>name</var> should
  56 be unused in
  57 the target.  If the target already has send rights, then those
  58 send rights gain an
  59 additional user reference.  Otherwise, the target gains a send
  60 right, with a user
  61 reference count of one.
  62 <p>
  63 If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or
  64 <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>, then a send-once right is inserted.
  65 The <var>name</var> should be unused in the target.  The
  66 target gains a send-once right.
  67 <p>
  68 If <var>right_type</var> is <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>, then a receive right is
  69 inserted.  If the target already holds send rights for the port,
  70 then <var>name</var> should
  71 denote those rights in the target.  Otherwise, <var>name</var> should be
  72 unused in the target.
  73 The receive right is moved into the target task.
  74 <h3>NOTES</h3>
  75 <p>
  76 This interface is machine word length specific because of the port name
  77 parameter.
  78 <h3>RETURN VALUES</h3>
  79 <dl>
  80 <p>
  81 <dt> <strong>KERN_NAME_EXISTS</strong>
  82 <dd>
  83 <var>name</var> already denoted a right.
  84 <p>
  85 <dt> <strong>KERN_INVALID_CAPABILITY</strong>
  86 <dd>
  87 <var>right</var> was null or dead.
  88 <p>
  89 <dt> <strong>KERN_UREFS_OVERFLOW</strong>
  90 <dd>
  91 Inserting the right would overflow <var>name</var>'s user-reference count.
  92 <p>
  93 <dt> <strong>KERN_RIGHT_EXISTS</strong>
  94 <dd>
  95 <var>task</var> already had rights for the port, with a different name.
  96 </dl>
  97 <h3>RELATED INFORMATION</h3>
  98 <p>
  99 Functions:
 100 <a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>,
 101 <a href="mach_msg.html"><strong>mach_msg</strong></a>.