-<h2>mach_port_mod_refs</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Modify the specified port right's count of user references.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_mod_refs</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_right_t</strong> <var>right</var>,
\r <strong>mach_port_delta_t</strong> <var>delta</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]
\rThe task holding the right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the right.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[in scalar]
\rThe type of right/entity being modified:
\r<dl>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_SEND</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_RECEIVE</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_PORT_SET</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
\r</dl>
\r<p>
\r<dt> <var>delta</var>
\r<dd>
\r[in scalar]
\rSigned change to the number of user references.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_mod_refs</strong> function requests that the number
\rof user references a task has for a right be changed. This results
\rin the right
\rbeing destroyed, if the
\rnumber of user references is changed to zero.
\r<p>
\rThe <var>name</var> parameter
\rshould denote the specified right. The number of user references for
\rthe right is changed by the amount <var>delta</var>, subject to the following
\rrestrictions:
\rport sets, receive rights, and send-once rights may only have
\rone user reference.
\rThe resulting number of user references can't be negative. If the resulting
\rnumber of user references is zero, the effect is to de-allocate
\rthe right. For dead
\rnames and send rights, there is an implementation-defined maximum number of
\ruser references.
\r<p>
\rIf the call destroys the right, then the effect is as described for
\r<strong>mach_port_destroy</strong>, with the exception that
\r<strong>mach_port_destroy</strong>
\rsimultaneously destroys all
\rthe rights denoted by a name, while <strong>mach_port_mod_refs</strong>
\rcan only destroy
\rone right. The name will be available for reuse if it only denoted
\rthe one right.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted a right, but not the specified right.
\r<p>
\r<dt> <strong>KERN_INVALID_VALUE</strong>
\r<dd>
\rThe user-reference count would become negative.
\r<p>
\r<dt> <strong>KERN_UREFS_OVERFLOW</strong>
\r<dd>
\rThe user-reference count would overflow.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_destroy.html"><strong>mach_port_destroy</strong></a>,
\r<a href="mach_port_get_refs.html"><strong>mach_port_get_refs</strong></a>.
\r\ No newline at end of file
+<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>.
projects / apple / xnu.git / blobdiff