osfmk/man/mach_port_mod_refs.html

   1 <h2>mach_port_mod_refs</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Modify the specified port right's count of user references.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   mach_port_mod_refs</strong>
   8                 <strong>(ipc_space_t</strong>                               <var>task</var>,
   9                  <strong>mach_port_name_t</strong>                          <var>name</var>,
  10                  <strong>mach_port_right_t</strong>                        <var>right</var>,
  11                  <strong>mach_port_delta_t</strong>                        <var>delta</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 holding the right.
  20 <p>
  21 <dt> <var>name</var>
  22 <dd>
  23 [in scalar]
  24 The task's name for the right.
  25 <p>
  26 <dt> <var>right</var>
  27 <dd>
  28 [in scalar]
  29 The type of right/entity being modified:
  30 <dl>
  31 <p>
  32 <dt>
  33 <strong>MACH_PORT_RIGHT_SEND</strong>
  34 <p>
  35 <dt>
  36 <strong>MACH_PORT_RIGHT_RECEIVE</strong>
  37 <p>
  38 <dt>
  39 <strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
  40 <p>
  41 <dt>
  42 <strong>MACH_PORT_RIGHT_PORT_SET</strong>
  43 <p>
  44 <dt>
  45 <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
  46 </dl>
  47 <p>
  48 <dt> <var>delta</var>
  49 <dd>
  50 [in scalar]
  51 Signed change to the number of user references.
  52 </dl>
  53 <h3>DESCRIPTION</h3>
  54 <p>
  55 The <strong>mach_port_mod_refs</strong> function requests that the number
  56 of user references a task has for a right be changed.  This results
  57 in the right
  58 being destroyed, if the
  59 number of user references is changed to zero.
  60 <p>
  61 The <var>name</var> parameter
  62 should denote the specified right.  The number of user references for
  63 the right is changed by the amount <var>delta</var>, subject to the following
  64 restrictions:
  65 port sets, receive rights, and send-once rights may only have
  66 one user reference.
  67 The resulting number of user references can't be negative.  If the resulting
  68 number of user references is zero, the effect is to de-allocate
  69 the right.  For dead
  70 names and send rights, there is an implementation-defined maximum number of
  71 user references.
  72 <p>
  73 If the call destroys the right, then the effect is as described for
  74 <strong>mach_port_destroy</strong>, with the exception that
  75 <strong>mach_port_destroy</strong>
  76 simultaneously destroys all
  77 the rights denoted by a name, while <strong>mach_port_mod_refs</strong>
  78 can only destroy
  79 one right.  The name will be available for reuse if it only denoted
  80 the one right.
  81 <h3>NOTES</h3>
  82 <p>
  83 This interface is machine word length specific because of the port name
  84 parameter.
  85 <h3>RETURN VALUES</h3>
  86 <dl>
  87 <p>
  88 <dt> <strong>KERN_INVALID_NAME</strong>
  89 <dd>
  90 <var>name</var> did not denote a right.
  91 <p>
  92 <dt> <strong>KERN_INVALID_RIGHT</strong>
  93 <dd>
  94 <var>name</var> denoted a right, but not the specified right.
  95 <p>
  96 <dt> <strong>KERN_INVALID_VALUE</strong>
  97 <dd>
  98 The user-reference count would become negative.
  99 <p>
 100 <dt> <strong>KERN_UREFS_OVERFLOW</strong>
 101 <dd>
 102 The user-reference count would overflow.
 103 </dl>
 104 <h3>RELATED INFORMATION</h3>
 105 <p>
 106 Functions:
 107 <a href="mach_port_destroy.html"><strong>mach_port_destroy</strong></a>,
 108 <a href="mach_port_get_refs.html"><strong>mach_port_get_refs</strong></a>.