osfmk/man/task_create.html

   1 <h2>task_create</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Create a new task.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   task_create</strong>
   8                 <strong>(task_t</strong>                             <var>parent_task</var>,
   9                  <strong>ledger_port_array_t</strong>                    <var>ledgers</var>,
  10                  <strong>int</strong>                               <var>ledger_count</var>,
  11                  <strong>boolean_t</strong>                       <var>inherit_memory</var>,
  12                  <strong>task_t</strong>                              <var>child_task</var><strong>);</strong>
  13 </pre>
  14 <h3>PARAMETERS</h3>
  15 <dl>
  16 <p>
  17 <dt> <var>parent_task</var>
  18 <dd>
  19 [in task send right]
  20 The port for the task from which to draw the child
  21 task's port rights and address space.
  22 <p>
  23 <dt> <var>ledgers</var>
  24 <dd>
  25 [pointer to in array of ledger send rights]
  26 Resource ledgers (on the
  27 destination host) from which the task will draw its resources.  The first
  28 element of this array is the wired kernel ledger, the second the paged
  29 space ledger.  If the number of ledgers supplied does not match the
  30 required number or one or more is null, the parent task's ledger is used.
  31 <p>
  32 <dt> <var>ledger_count</var>
  33 <dd>
  34 [in scalar]
  35 The number of ledger ports in the <var>ledgers</var> array.
  36 <p>
  37 <dt> <var>inherit_memory</var>
  38 <dd>
  39 [in scalar]
  40 Address space inheritance indicator.  If true, the child task
  41 inherits the (inheritable) address space of the parent task.  If false, the
  42 kernel assigns the child task an empty address space.
  43 <p>
  44 <dt> <var>child_task</var>
  45 <dd>
  46 [out task send right]
  47 The kernel-assigned port for the new task.
  48 </dl>
  49 <h3>DESCRIPTION</h3>
  50 <p>
  51 The <strong>task_create</strong> function creates a new task from <var>parent_task</var>
  52 and returns the name of the new task in <var>child_task</var>.
  53 The child task acquires shared or copied parts of the parent's address space
  54 (see <strong>vm_inherit</strong>).  The child task initially
  55 contains no threads.  The child task inherits the parent's security ID.
  56 <p>
  57 The child task receives the following "special" ports, which are created or
  58 copied for it at task creation:
  59 <dl>
  60 <dt> [task-self send right]
  61 <dd>
  62 The port by which the kernel knows the new child task
  63 and allows it to be manipulated.  The child task holds a send right for this
  64 port.  The port name is also returned to the calling task.
  65 <p>
  66 <dt> [bootstrap send right]
  67 <dd>
  68 The port to which the child task can send a message
  69 requesting return of any system service ports that it needs (for
  70 example, a port
  71 to the Network Name Server or the Environment Manager).  The child task
  72 inherits a send right for this port from the parent task.  The task can use
  73 <strong>task_set_special_port</strong> to change this port.
  74 <p>
  75 <dt> [host-self send right]
  76 <dd>
  77 The port by which the child task requests information
  78 about its host.  The child task inherits a send right for this port from the
  79 parent task.
  80 <p>
  81 <dt> [ledger send rights]
  82 <dd>
  83 The ports naming the ledgers from which the task draws
  84 its resources.
  85 </dl>
  86 <p>
  87 The child task also inherits the following ports:
  88 <dl>
  89 <dt> [sample send right]
  90 <dd>
  91 The port to which PC sampling messages are to be sent.
  92 <p>
  93 <dt> [exception send rights]
  94 <dd>
  95 Ports to which exception messages are sent.
  96 <p>
  97 <dt> [registered send rights]
  98 <dd>
  99 Ports to system services.
 100 </dl>
 101 <h3>NOTES</h3>
 102 <p>
 103 The <strong>ledgers</strong> functionality mentioned above is not
 104 currently implemented.
 105 <h3>RETURN VALUES</h3>
 106 <p>
 107 Only generic errors apply.
 108 <h3>RELATED INFORMATION</h3>
 109 <p>
 110 Functions:
 111 <a href="task_create_security_token.html"><strong>task_create_security_token</strong></a>,
 112 <a href="task_resume.html"><strong>task_resume</strong></a>,
 113 <a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
 114 <a href="task_suspend.html"><strong>task_suspend</strong></a>,
 115 <a href="task_terminate.html"><strong>task_terminate</strong></a>,
 116 <a href="task_threads.html"><strong>task_threads</strong></a>,
 117 <a href="thread_create.html"><strong>thread_create</strong></a>,
 118 <a href="thread_resume.html"><strong>thread_resume</strong></a>,
 119 <a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
 120 <a href="task_sample.html"><strong>task_sample</strong></a>,
 121 <a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
 122 <a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>,
 123 <a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>.