mach_port_allocate_name

Function - Create a port right with the caller-specified name.

SYNOPSIS

kern_return_t   mach_port_allocate_name
                (ipc_space_t                               task,
                 mach_port_right_t                        right,
                 mach_port_name_t                          name);

PARAMETERS

task

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

right

[in scalar] The kind of entity to be created. This is one of the following:

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 dead name. The new dead name has one user reference.

name

[in scalar] The task's name for the port 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.

DESCRIPTION

The mach_port_allocate_name function creates a new right in the specified task, with a specified name for the new right.

NOTES

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

RETURN VALUES

KERN_NAME_EXISTS

name was already in use for a port right.

RELATED INFORMATION

Functions: mach_port_allocate, mach_port_deallocate, mach_port_insert_right, mach_port_extract_right.