NAME
mach_ports_register - manipulate the inherited ports array
mach_ports_lookup - child port acquires specific parent ports

SYNOPSIS
#include <mach.h>

kern_return_t mach_ports_register(target_task,
init_port_set, init_port_array_count)
task_t target_task;
port_array_t init_port_set; /* array */
int init_port_array_count;

kern_return_t mach_ports_lookup(target_task,
init_port_set, init_port_array_count)
task_t target_task;
port_array_t *init_port_set; /* out array */
int *init_port_array_count; /* out */

ARGUMENTS
target_task Task to be affected.

init_port_set An array of system ports to be registered, or
returned. Although the array size is given as
variable, the kernel will only accept a limited
number of ports.

init_port_array_count
The number of ports returned in init_port_set.

DESCRIPTION
mach_ports_register registers an array of well-known system ports
with the kernel on behalf of a specific task. Currently the ports
to be registered are: the port to the Network Name Server, the port
to the Environment Manager, and a port to the Service server. These
port values must be placed in specific slots in the init_port_set.
The slot numbers are given by the global constants defined in
mach_init.h: NAME_SERVER_SLOT, ENVIRONMENT_SLOT, and SERVICE_SLOT.
These ports may later be retrieved with mach_ports_lookup.

When a new task is created (see task_create), the child task will
be given access to these ports. Only port send rights may be
registered. Furthermore, the number of ports which may be
registered is fixed and given by the global constant
MACH_PORT_SLOTS_USED. Attempts to register too many ports will
fail.

It is intended that this mechanism be used only for task
initialization, and then only by runtime support modules. A parent
task has three choices in passing these system ports to a child
task. Most commonly it can do nothing and its child will inherit
access to the same init_port_set that the parent has; or a parent
task may register a set of ports it wishes to have passed to all of
its children by calling mach_ports_register using its task port;
or it may make necessary modifications to the set of ports it
wishes its child to see, and then register those ports using the
child’s task port prior to starting the child’s thread(s). The
mach_ports_lookup call which is done by mach_init in the child
task will acquire these initial ports for the child.

Tasks other than the Network Name Server and the Environment
Manager should not need access to the Service port. The Network
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.

Since the number of ports which may be registered is limited, ports
other than those used by the runtime system to initialize a task
should be passed to children either through an initial message, or
through the Network Name Server for public ports, or the
Environment Manager for private ports.

DIAGNOSTICS
KERN_SUCCESS Memory allocated.

KERN_INVALID_ARGUMENT An attempt was made to register more
ports than the current kernel
implementation allows.