— Function: kern_return_t mach_port_get_refs (ipc_space_t task, mach_port_t name, mach_port_right_t right, mach_port_urefs_t *refs)

The function mach_port_get_refs returns the number of user references a task has for a right.

The right argument takes the following values:

• MACH_PORT_RIGHT_SEND
• MACH_PORT_RIGHT_RECEIVE
• MACH_PORT_RIGHT_SEND_ONCE
• MACH_PORT_RIGHT_PORT_SET
• MACH_PORT_RIGHT_DEAD_NAME

If name denotes a right, but not the type of right specified, then zero is returned. Otherwise a positive number of user references is returned. Note that a name may simultaneously denote send and receive rights.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid and KERN_INVALID_NAME if name did not denote a right.

The mach_port_get_refs call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

— Function: kern_return_t mach_port_mod_refs (ipc_space_t task, mach_port_t name, mach_port_right_t right, mach_port_delta_t delta)

The function mach_port_mod_refs 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 task holding the right is task, name should denote the specified right. right denotes the type of right being modified. delta is the signed change to the number of user references.

The right argument takes the following values:

• MACH_PORT_RIGHT_SEND
• MACH_PORT_RIGHT_RECEIVE
• MACH_PORT_RIGHT_SEND_ONCE
• MACH_PORT_RIGHT_PORT_SET
• MACH_PORT_RIGHT_DEAD_NAME

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 deallocate 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.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid or the user-reference count would become negative, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted a right, but not the specified right and KERN_UREFS_OVERFLOW if the user-reference count would overflow.

The mach_port_mod_refs call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.