mach_port_mod_refs

Function - Modify the specified port right's count of user references.

SYNOPSIS

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);

PARAMETERS

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.

DESCRIPTION

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.

NOTES

This interface is machine word length specific because of the port name parameter.

RETURN VALUES

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.

RELATED INFORMATION

Functions: mach_port_destroy, mach_port_get_refs.