mach_port_extract_right

Function - Remove the specified right from the target task and return it to the caller.

SYNOPSIS

kern_return_t   mach_port_extract_right
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_msg_type_name_t              desired_type,
                 mach_port_poly_t                        *right,
                 mach_msg_type_name_             *acquired_type);

PARAMETERS

task

[in task send right] The task holding the port right.

name

[in scalar] The task's name for the port right.

desired_type

[in scalar] IPC type, specifying how the right should be extracted.

right

[out random right] The extracted right.

acquired_type

[out scalar] The type of the extracted right.

DESCRIPTION

The mach_port_extract_right function extracts a port right from the target task and returns it to the caller as if the task sent the right voluntarily, using desired_type as the disposition for the right. See mach_msg.

The returned value of acquired_type will be MACH_MSG_TYPE_PORT_SEND if a send right is extracted, MACH_MSG_TYPE_PORT_RECEIVE if a receive right is extracted, and MACH_MSG_TYPE_PORT_SEND_ONCE if a send-once right is extracted.

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 an invalid right.

RELATED INFORMATION

Functions: mach_port_insert_right, mach_msg.