task_create

Function - Create a new task.

SYNOPSIS

kern_return_t   task_create
                (task_t                             parent_task,
                 ledger_port_array_t                    ledgers,
                 int                               ledger_count,
                 boolean_t                       inherit_memory,
                 task_t                              child_task);

PARAMETERS

parent_task

[in task send right] The port for the task from which to draw the child task's port rights and address space.

ledgers

[pointer to in array of ledger send rights] Resource ledgers (on the destination host) from which the task will draw its resources. The first element of this array is the wired kernel ledger, the second the paged space ledger. If the number of ledgers supplied does not match the required number or one or more is null, the parent task's ledger is used.

ledger_count

[in scalar] The number of ledger ports in the ledgers array.

inherit_memory

[in scalar] Address space inheritance indicator. If true, the child task inherits the (inheritable) address space of the parent task. If false, the kernel assigns the child task an empty address space.

child_task

[out task send right] The kernel-assigned port for the new task.

DESCRIPTION

The task_create function creates a new task from parent_task and returns the name of the new task in child_task. The child task acquires shared or copied parts of the parent's address space (see vm_inherit). The child task initially contains no threads. The child task inherits the parent's security ID.

The child task receives the following "special" ports, which are created or copied for it at task creation:

[task-self send right]

The port by which the kernel knows the new child task and allows it to be manipulated. The child task holds a send right for this port. The port name is also returned to the calling task.

[bootstrap send right]

The port to which the child task can send a message requesting return of any system service ports that it needs (for example, a port to the Network Name Server or the Environment Manager). The child task inherits a send right for this port from the parent task. The task can use task_set_special_port to change this port.

[host-self send right]

The port by which the child task requests information about its host. The child task inherits a send right for this port from the parent task.

[ledger send rights]

The ports naming the ledgers from which the task draws its resources.

The child task also inherits the following ports:

[sample send right]

The port to which PC sampling messages are to be sent.

[exception send rights]

Ports to which exception messages are sent.

[registered send rights]

Ports to system services.

NOTES

The ledgers functionality mentioned above is not currently implemented.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: task_create_security_token, task_resume, task_set_special_port, task_suspend, task_terminate, task_threads, thread_create, thread_resume, vm_inherit, task_sample, task_set_exception_ports, mach_ports_register, norma_task_create, task_set_security_token.