— Function: kern_return_t mach_port_insert_right (ipc_space_t task, mach_port_t name, mach_port_t right, mach_msg_type_name_t right_type)

The function mach_port_insert_right 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 msgt_name; see 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.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was not a port right or name was MACH_PORT_NULL or MACH_PORT_DEAD, KERN_NAME_EXISTS if name already denoted a right, KERN_INVALID_CAPABILITY if right was MACH_PORT_NULL or MACH_PORT_DEAD KERN_RIGHT_EXISTS if task already had rights for the port, with a different name, KERN_UREFS_OVERFLOW if the user-reference count would overflow and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_insert_right 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_extract_right (ipc_space_t task, mach_port_t name, mach_msg_type_name_t desired_type, mach_port_t *right, mach_msg_type_name_t *acquired_type)

The function mach_port_extract_right 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 value of msgt_name. See Mach Message Call.

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.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted a right, but an invalid one, KERN_INVALID_VALUE if desired_type was invalid.

The mach_port_extract_right 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.