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