xnu-7195.101.1.tar.gz

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

<h2>mach_port_mod_refs</h2>
<hr>
<p>
<strong>Function</strong> - Modify the specified port right's count of user references.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   mach_port_mod_refs</strong>
                <strong>(ipc_space_t</strong>                               <var>task</var>,
                 <strong>mach_port_name_t</strong>                          <var>name</var>,
                 <strong>mach_port_right_t</strong>                        <var>right</var>,
                 <strong>mach_port_delta_t</strong>                        <var>delta</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>task</var> 
<dd>
[in task send right]
The task holding the right.
<p>
<dt> <var>name</var> 
<dd>
[in scalar]
The task's name for the right.
<p>
<dt> <var>right</var> 
<dd>
[in scalar]
The type of right/entity being modified:
<dl>
<p>
<dt>
<strong>MACH_PORT_RIGHT_SEND</strong>
<p>
<dt>
<strong>MACH_PORT_RIGHT_RECEIVE</strong>
<p>
<dt>
<strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
<p>
<dt>
<strong>MACH_PORT_RIGHT_PORT_SET</strong>
<p>
<dt>
<strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
</dl>
<p>
<dt> <var>delta</var> 
<dd>
[in scalar]
Signed change to the number of user references.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>mach_port_mod_refs</strong> function requests that the number
of user references a task has for a right be changed.  This results 
in the right
being destroyed, if the 
number of user references is changed to zero. 
<p>
The <var>name</var> parameter
should denote the specified right.  The number of user references for 
the right is changed by the amount <var>delta</var>, subject to the following
restrictions: 
port sets, receive rights, and send-once rights may only have
one user reference. 
The resulting number of user references can't be negative.  If the resulting
number of user references is zero, the effect is to de-allocate
the right.  For dead 
names and send rights, there is an implementation-defined maximum number of 
user references. 
<p>
If the call destroys the right, then the effect is as described for
<strong>mach_port_destroy</strong>, with the exception that 
<strong>mach_port_destroy</strong>
simultaneously destroys all 
the rights denoted by a name, while <strong>mach_port_mod_refs</strong>
can only destroy 
one right.  The name will be available for reuse if it only denoted
the one right.
<h3>NOTES</h3>
<p>
This interface is machine word length specific because of the port name
parameter.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_INVALID_NAME</strong>
<dd>
<var>name</var> did not denote a right.
<p>
<dt> <strong>KERN_INVALID_RIGHT</strong>
<dd>
<var>name</var> denoted a right, but not the specified right.
<p>
<dt> <strong>KERN_INVALID_VALUE</strong>
<dd>
The user-reference count would become negative.
<p>
<dt> <strong>KERN_UREFS_OVERFLOW</strong>
<dd>
The user-reference count would overflow.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="mach_port_destroy.html"><strong>mach_port_destroy</strong></a>,
<a href="mach_port_get_refs.html"><strong>mach_port_get_refs</strong></a>.