mach_ports_register

Function - Register an array of well-known ports on behalf of the target task.

SYNOPSIS

kern_return_t   mach_ports_register
                (task_t                             target_task,
                 mach_port_array_t                init_port_set,
                 target_task              init_port_array_count);

PARAMETERS

target_task

[in task send right] The task for which the ports are to be registered.

init_port_set

[in pointer to array of registered send rights] The array of ports to register.

init_port_array_count

[in scalar] The number of ports in the array. Note that while this is a variable, the kernel accepts only a limited number of ports. The maximum number of ports is defined by the global constant MACH_PORTS_SLOTS_USED.

DESCRIPTION

The mach_ports_register function registers an array of well-known system ports for the specified task. The task holds only send rights for the registered ports. The valid well-known system ports are:

• The port for the Name Server
• The port for the Environment Manager
• The port for the Service server

Each port must be placed in a specific slot in the array. The slot numbers are defined (in mach.h) by the global constants NAME_SERVER_SLOT, ENVIRONMENT_SLOT, and SERVICE_SLOT.

A task can retrieve the currently registered ports by using the mach_ports_lookup function.

NOTES

When a new task is created (with task_create), the child task can inherit the parent's registered ports. Note that child tasks do not automatically acquire rights to these ports. They must use mach_ports_lookup to get them. It is intended that port registration be used only for task initialization, and then only by run-time support modules.

A parent task has three choices when passing registered ports to child tasks:

• The parent task can do nothing. In this case, all child tasks inherit access to the same ports that the parent has.
• The parent task can use mach_ports_register to modify its set of registered ports before creating child tasks. In this case, the child tasks get access to the modified set of ports. After creating its child tasks. the parent can use mach_ports_register again to reset its registered ports.
• The parent task can first create a specific child task and then use mach_ports_register to modify the child's inherited set of ports, before starting the child's thread(s). The parent must specify the child's task port, rather than its own, on the call to mach_ports_register.

Tasks other than the Name Server and the Environment Manager should not need access to the Service port. The Name Server port is the same for all tasks on a given machine. The Environment port is the only port likely to have different values for different tasks.

Registered ports are restricted to those ports that are used by the run-time system to initialize a task. A parent task can pass other ports to its child tasks through:

• An initial message (see mach_msg).
• The Name Server, for public ports.
• The Environment Manager, for private ports.
• The task bootstrap port (see task_get_special_port).

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_msg, mach_ports_lookup.