mach_port_insert_right

Function - Insert the specified port right into the target task.

SYNOPSIS

kern_return_t   mach_port_insert_right
                (ipc_space_t                               task,
                 mach_port_name_t                          name,
                 mach_port_poly_t                         right,
                 mach_msg_type_name_t                right_type);

PARAMETERS

task

[in task send right] The task which gets the caller's right.

name

[in scalar] The name by which task will know the right.

right

[in random right] The port right.

right_type

[in scalar] IPC type of the sent right; e.g., MACH_MSG_TYPE_COPY_SEND or MACH_MSG_TYPE_MOVE_RECEIVE.

DESCRIPTION

The mach_port_insert_right function inserts into task the caller's right for a port, using a specified name for the right in the target task.

The specified name can't be one of the reserved values MACH_PORT_NULL or MACH_PORT_DEAD. The right can't be MACH_PORT_NULL or MACH_PORT_DEAD.

The argument right_type specifies a right to be inserted and how that right should be extracted from the caller. It should be a value appropriate for mach_msg.

If right_type is MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or MACH_MSG_TYPE_COPY_SEND, then a send right is inserted. If the target already holds send or receive rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. If the target already has send rights, then those send rights gain an additional user reference. Otherwise, the target gains a send right, with a user reference count of one.

If right_type is MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE, then a send-once right is inserted. The name should be unused in the target. The target gains a send-once right.

If right_type is MACH_MSG_TYPE_MOVE_RECEIVE, then a receive right is inserted. If the target already holds send rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. The receive right is moved into the target task.

NOTES

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

RETURN VALUES

KERN_NAME_EXISTS

name already denoted a right.

KERN_INVALID_CAPABILITY

right was null or dead.

KERN_UREFS_OVERFLOW

Inserting the right would overflow name's user-reference count.

KERN_RIGHT_EXISTS

task already had rights for the port, with a different name.

RELATED INFORMATION

Functions: mach_port_extract_right, mach_msg.