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

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