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