osfmk/man/mach_port_mod_refs.html
Function - Modify the specified port right's count of user references.
**kern\_return\_t mach\_port\_mod\_refs**** (ipc\_space\_t **task,** mach\_port\_name\_t **name,** mach\_port\_right\_t **right,** mach\_port\_delta\_t **delta** );**
task[in task send right] The task holding the right.
name[in scalar] The task's name for the right.
right[in scalar] The type of right/entity being modified:
MACH_PORT_RIGHT_SEND
MACH_PORT_RIGHT_RECEIVE
MACH_PORT_RIGHT_SEND_ONCE
MACH_PORT_RIGHT_PORT_SET
MACH_PORT_RIGHT_DEAD_NAME
delta[in scalar] Signed change to the number of user references.
The mach_port_mod_refs 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.
The name parameter should denote the specified right. The number of user references for the right is changed by the amount delta, 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.
If the call destroys the right, then the effect is as described for mach_port_destroy , with the exception that mach_port_destroy simultaneously destroys all the rights denoted by a name, while mach_port_mod_refs can only destroy one right. The name will be available for reuse if it only denoted the one right.
This interface is machine word length specific because of the port name parameter.
KERN_INVALID_NAME name did not denote a right.
KERN_INVALID_RIGHT name denoted a right, but not the specified right.
KERN_INVALID_VALUE The user-reference count would become negative.
KERN_UREFS_OVERFLOW The user-reference count would overflow.
Functions: mach_port_destroy, mach_port_get_refs.