| | 1 | <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 |
projects / apple / xnu.git / blame_incremental