xnu-2050.48.11.tar.gz

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

<h2>norma_task_clone</h2>
<hr>
<p>
<strong>Function</strong> - Create a remote task that shares access to parent task's memory regardless of inheritance attributes.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   norma_task_clone</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
inherits 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 <strong>norma_task_clone</strong> function "clones" a new task from
<var>parent_task</var> on the specified <var>node</var> and returns the name 
of the new task in <var>child_task</var>.  The child 
task acquires shared parts of the parent's 
address space (see <strong>vm_inherit</strong>)
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.
<p>
By way of comparison, tasks created by the standard <strong>task_create</strong>
primitive are created on the same node as the parent.
<p>
Other than being created on a different node, the new task has the same
properties as if created by <strong>task_create</strong>.
<h3>NOTES</h3>
<p>
This call differs from <strong>norma_task_create</strong> in that the
inheritance set for the
parent's memory regions is ignored; the child always shares memory with the
parent.
<p>
This call is intended to support process migration, where the inheritance
semantics of <strong>norma_task_create</strong> would break migrated
programs that depended upon 
sharing relationships remaining after migration.
<p>
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="task_create.html"><strong>task_create</strong></a>,
<a href="norma_task_create.html"><strong>norma_task_create</strong></a>.