4.3.3 Port Names

Function: kern_return_t mach_port_names (ipc_space_t task, mach_port_array_t *names, mach_msg_type_number_t *ncount, mach_port_type_array_t *types, mach_msg_type_number_t *tcount)

The function mach_port_names returns information about task’s port name space. For each name, it also returns what type of rights task holds. (The same information returned by mach_port_type.) names and types are arrays that are automatically allocated when the reply message is received. The user should vm_deallocate them when the data is no longer needed.

mach_port_names will return in names the names of the ports, port sets, and dead names in the task’s port name space, in no particular order and in ncount the number of names returned. It will return in types the type of each corresponding name, which indicates what kind of rights the task holds with that name. tcount should be the same as ncount.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_names 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_type (ipc_space_t task, mach_port_t name, mach_port_type_t *ptype)

The function mach_port_type returns information about task’s rights for a specific name in its port name space. The returned ptype is a bitmask indicating what rights task holds for the port, port set or dead name. The bitmask is composed of the following bits:

MACH_PORT_TYPE_SEND

The name denotes a send right.

MACH_PORT_TYPE_RECEIVE

The name denotes a receive right.

MACH_PORT_TYPE_SEND_ONCE

The name denotes a send-once right.

MACH_PORT_TYPE_PORT_SET

The name denotes a port set.

MACH_PORT_TYPE_DEAD_NAME

The name is a dead name.

MACH_PORT_TYPE_DNREQUEST

A dead-name request has been registered for the right.

MACH_PORT_TYPE_MAREQUEST

A msg-accepted request for the right is pending.

MACH_PORT_TYPE_COMPAT

The port right was created in the compatibility mode.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid and KERN_INVALID_NAME if name did not denote a right.

The mach_port_type 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_rename (ipc_space_t task, mach_port_t old_name, mach_port_t new_name)

The function mach_port_rename changes the name by which a port, port set, or dead name is known to task. old_name is the original name and new_name the new name for the port right. new_name must not already be in use, and it can’t be the distinguished values MACH_PORT_NULL and MACH_PORT_DEAD.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if old_name did not denote a right, KERN_INVALID_VALUE if new_name was MACH_PORT_NULL or MACH_PORT_DEAD, KERN_NAME_EXISTS if new_name already denoted a right and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

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