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