xnu-2050.48.11.tar.gz

[apple/xnu.git] / osfmk / man / norma_task_teleport.html

<h2>norma_task_teleport</h2>
<hr>
<p>
<strong>Function</strong> - "Clone" a task on a specified node.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   norma_task_teleport</strong>
                <strong>(task_t</strong>                             <var>parent_task</var>,
                 <strong>boolean_t</strong>                       <var>inherit_memory</var>,
                 <strong>int</strong>                                 <var>child_node</var>,
                 <strong>task_t</strong>                              <var>child_task</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>parent_task</var>
<dd>
[in task send right] The port for the task from which to draw the child 
task's port rights, resource limits, and address space.
<p>
<dt> <var>inherit_memory</var>
<dd>
[in scalar] Address space inheritance indicator. If true, the child task in-
herits the address space of the parent task. If false, the kernel assigns 
the child task an empty address space.
<p>
<dt> <var>child_node</var>
<dd>
[in scalar] The node index of the node on which to create the child.
<p>
<dt> <var>child_task</var>
<dd>
[out task send right] The kernel-assigned port name for the new task.
</dl>
<h3>DESCRIPTION</h3>
<p>
The norma_task_clone function "clones" a new task from parent_task on
the specified node and returns the name of the new task in
child_task. The child task acquires shared parts of the parent's
address space (see vm_inherit) regardless of the inheritance set for
the parent's memory regions, although the inheritance for the
child's regions will be set to that of the parent's regions. The child
task initially contains no threads. The parent_task is then
terminated.
By way of comparison, tasks created by the standard task_create
primitive are created on the same node as the parent.
Other than being created on a different node, the new task has the
same properties as if created by task_create.
<h3>NOTES</h3>
<p>
This call differs from norma_task_clone in that the parent task is
terminated as part of the teleport call.
This call differs from norma_task_create in that the inheritance set
for the parent's memory regions is ignored; the child always shares
memory with the parent.
This call is intended to support process migration, where the
inheritance semantics of norma_task_create would break migrated
programs that depended upon sharing relationships remaining after
migration.
This call is not a true task migration call, in that it does not
migrate the port space, threads, and other non-address-space
attributes of the task.
<h3>RETURN VALUES</h3>
<p>
Only generic errors apply.
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>,
<a href="task_create.html"><strong>task_create</strong></a>,
<a href="norma_task_create.html"><strong>norma_task_create</strong></a>,