mach_port_allocate

Function - Create caller-specified type of port right.

SYNOPSIS

kern_return_t   mach_port_allocate
                (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 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.

name

[out scalar] The task's name for the port right. This can be any name that wasn't in use.

DESCRIPTION

The mach_port_allocate function creates a new right in the specified task. The new right's name is returned in name.

Ports that are allocated via this call do not support the full set of Mach port semantics; in particular, the kernel will not provide no-more-senders notification service requests on such ports. Any attempt to request no-more-senders notification service will generate an error. Use the mach_port_allocate_full interface to allocate ports that support the full set of Mach port semantics.

NOTES

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

RETURN VALUES

KERN_NO_SPACE

There was no room in task's IPC name space for another right.

RELATED INFORMATION

Functions: mach_port_allocate_name, mach_port_deallocate, mach_port_insert_right, mach_port_extract_right.