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:

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:

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:

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: mach_msg, mach_ports_lookup.