— Function: kern_return_t mach_port_allocate (ipc_space_t task, mach_port_right_t right, mach_port_t *name)

The mach_port_allocate function creates a new right in the specified task. The new right's name is returned in name, which may be any name that wasn't in use.

The right argument takes the following values:

MACH_PORT_RIGHT_RECEIVE

mach_port_allocate creates a port. The new port is not a member of any port set. It doesn't have any extant send or send-once rights. Its make-send count is zero, its sequence number is zero, its queue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued messages. name denotes the receive right for the new port.

task does not hold send rights for the new port, only the receive right. mach_port_insert_right and mach_port_extract_right can be used to convert the receive right into a combined send/receive right.

MACH_PORT_RIGHT_PORT_SET

mach_port_allocate creates a port set. The new port set has no members.

MACH_PORT_RIGHT_DEAD_NAME

mach_port_allocate creates a dead name. The new dead name has one user reference.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid, KERN_NO_SPACE if there was no room in task's IPC name space for another right and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_allocate 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: mach_port_t mach_reply_port ()

The mach_reply_port system call creates a reply port in the calling task.

mach_reply_port creates a port, giving the calling task the receive right for the port. The call returns the name of the new receive right.

This is very much like creating a receive right with the mach_port_allocate call, with two differences. First, mach_reply_port is a system call and not an RPC (which requires a reply port). Second, the port created by mach_reply_port may be optimized for use as a reply port.

The function returns MACH_PORT_NULL if a resource shortage prevented the creation of the receive right.

— Function: kern_return_t mach_port_allocate_name (ipc_space_t task, mach_port_right_t right, mach_port_t name)

The function mach_port_allocate_name creates a new right in the specified task, with a specified name for the new right. name must not already be in use for some right, and it can't be the reserved values MACH_PORT_NULL and MACH_PORT_DEAD.

The right argument takes the following values:

MACH_PORT_RIGHT_RECEIVE

mach_port_allocate_name creates a port. The new port is not a member of any port set. It doesn't have any extant send or send-once rights. Its make-send count is zero, its sequence number is zero, its queue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued messages. name denotes the receive right for the new port.

task does not hold send rights for the new port, only the receive right. mach_port_insert_right and mach_port_extract_right can be used to convert the receive right into a combined send/receive right.

MACH_PORT_RIGHT_PORT_SET

mach_port_allocate_name creates a port set. The new port set has no members.

MACH_PORT_RIGHT_DEAD_NAME

mach_port_allocate_name creates a new dead name. The new dead name has one user reference.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid or name was MACH_PORT_NULL or MACH_PORT_DEAD, KERN_NAME_EXISTS if name was already in use for a port right and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

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