NAME
task_get_special_port - returns a special port of a task
task_set_special_port - set a special port of a task
task_self - returns calling thread’s task port
task_notify - returns calling thread’s task notification port

SYNOPSIS
#include <mach.h>

kern_return_t task_get_special_port(task, which_port, special_port)
task_t task;
int which_port;
port_t *special_port; /* out */

kern_return_t task_set_special_port(task, which_port, special_port)
task_t task;
int which_port;
port_t special_port;

task_t task_self()

port_t task_notify()

ARGUMENTS
task The task for which to get the port

which_port The port that is requested. Is one of
TASK_NOTIFY_PORT, TASK_BOOTSTRAP_PORT,
TASK_EXCEPTION_PORT.

special_port The value of the port that is being requested or
being set.

DESCRIPTION
get_special_port returns send rights to one of a set of special
ports for the task specified by task. In the case of the task’s
own task_notify_port, the task also gets receive and ownership
rights.

set_special_port sets one of a set of special ports for the task
specified by task.

task_self returns the port to which kernel calls for the currently
executing thread should be directed. Currently, task_self returns
the task kernel port which is a port for which the kernel has
receive rights and which it uses to identify a task. In the future
it may be possible for one task to interpose a port as another’s
task’s kernel port. At that time, task_self will still return the
port to which the executing thread should direct kernel calls, but
it may no longer be a port on which the kernel has receive rights.

If one task, the controller, has send access to the kernel port of
another task, the subject task, then the controller task can
perform kernel operations for the subject task. Normally only the
task itself and the task that created it will have access to the
task kernel port, but any task may pass rights to its kernel port
to any other task.

task_notify returns receive, ownership and send rights to the
notify port associated with the task to which the executing thread
belongs. The notify port is a port on which the task should receive
notification of such kernel events of the destruction of a port to
which it has send rights.

The other special ports associated with a task are the bootstrap
port and the exception port. The bootstrap port is a port to which
a thread may send a message requesting other system service ports.
This port is not used by the kernel. The task’s exception port is
the port to which messages are sent by the kernel when an exception
occurs and the thread causing the exception has no exception port
of its own.

Within the C environment, task_self and task_notify are implemented
as macros which execute the system traps the first time and
thereafter return a cached value for the ports. Thus it is
unnecessary for a programmer to cache these variables himself and
such caching may interfere with the future implementation of port
interposition.

The following macros to call task_set/get_special_port for a
specific port are defined in <sys/task_special_ports.h>:
task_get_notify_port, task_set_notify_port,
task_get_exception_port, task_set_exception_port,
task_get_bootstrap_port and task_set_bootstrap_port.

DIAGNOSTICS
KERN_SUCCESS The port was returned or set.

KERN_INVALID_ARGUMENT task is not a task or which_port is
an invalid port selector.

SEE ALSO
thread_special_ports(2), mach_init(3), task_create(2)

BUGS
The call on the bootstrap port to get system service ports has not
been implemented yet.

TASK_KERNEL_PORT may be added to the set of ports that
task_set_special_port accepts.