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]
19The task holding the right.
20<p>
21<dt> <var>name</var> 
22<dd>
23[in scalar]
24The task's name for the right.
25<p>
26<dt> <var>right</var> 
27<dd>
28[in scalar]
29The 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]
51Signed change to the number of user references.
52</dl>
53<h3>DESCRIPTION</h3>
54<p>
55The <strong>mach_port_mod_refs</strong> function requests that the number
56of user references a task has for a right be changed.  This results 
57in the right
58being destroyed, if the 
59number of user references is changed to zero. 
60<p>
61The <var>name</var> parameter
62should denote the specified right.  The number of user references for 
63the right is changed by the amount <var>delta</var>, subject to the following
64restrictions: 
65port sets, receive rights, and send-once rights may only have
66one user reference. 
67The resulting number of user references can't be negative.  If the resulting
68number of user references is zero, the effect is to de-allocate
69the right.  For dead 
70names and send rights, there is an implementation-defined maximum number of 
71user references. 
72<p>
73If 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>
76simultaneously destroys all 
77the rights denoted by a name, while <strong>mach_port_mod_refs</strong>
78can only destroy 
79one right.  The name will be available for reuse if it only denoted
80the one right.
81<h3>NOTES</h3>
82<p>
83This interface is machine word length specific because of the port name
84parameter.
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>
98The user-reference count would become negative.
99<p>
100<dt> <strong>KERN_UREFS_OVERFLOW</strong>
101<dd>
102The user-reference count would overflow.
103</dl>
104<h3>RELATED INFORMATION</h3>
105<p>
106Functions:
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>.
109