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]
20The port for the task from which to draw the child 
21task's port rights and address space.
22<p>
23<dt> <var>ledgers</var> 
24<dd>
25[pointer to in array of ledger send rights]
26Resource ledgers (on the
27destination host) from which the task will draw its resources.  The first
28element of this array is the wired kernel ledger, the second the paged 
29space ledger.  If the number of ledgers supplied does not match the
30required 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]
35The number of ledger ports in the <var>ledgers</var> array.
36<p>
37<dt> <var>inherit_memory</var> 
38<dd>
39[in scalar]
40Address space inheritance indicator.  If true, the child task
41inherits the (inheritable) address space of the parent task.  If false, the
42kernel assigns the child task an empty address space.
43<p>
44<dt> <var>child_task</var> 
45<dd>
46[out task send right]
47The kernel-assigned port for the new task.
48</dl>
49<h3>DESCRIPTION</h3>
50<p>
51The <strong>task_create</strong> function creates a new task from <var>parent_task</var>
52and returns the name of the new task in <var>child_task</var>.  
53The child task acquires shared or copied parts of the parent's address space 
54(see <strong>vm_inherit</strong>).  The child task initially
55contains no threads.  The child task inherits the parent's security ID.
56<p>
57The child task receives the following "special" ports, which are created or
58copied for it at task creation:
59<dl>
60<dt> [task-self send right]
61<dd>
62The port by which the kernel knows the new child task 
63and allows it to be manipulated.  The child task holds a send right for this 
64port.  The port name is also returned to the calling task.
65<p>
66<dt> [bootstrap send right]
67<dd>
68The port to which the child task can send a message
69requesting return of any system service ports that it needs (for
70example, a port 
71to the Network Name Server or the Environment Manager).  The child task 
72inherits 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>
77The port by which the child task requests information 
78about its host.  The child task inherits a send right for this port from the
79parent task.
80<p>
81<dt> [ledger send rights]
82<dd>
83The ports naming the ledgers from which the task draws 
84its resources.
85</dl>
86<p>
87The child task also inherits the following ports:
88<dl>
89<dt> [sample send right]
90<dd>
91The port to which PC sampling messages are to be sent.
92<p>
93<dt> [exception send rights]
94<dd>
95Ports to which exception messages are sent.
96<p>
97<dt> [registered send rights]
98<dd>
99Ports to system services.
100</dl>
101<h3>NOTES</h3>
102<p>
103The <strong>ledgers</strong> functionality mentioned above is not
104currently implemented.
105<h3>RETURN VALUES</h3>
106<p>
107Only generic errors apply.
108<h3>RELATED INFORMATION</h3>
109<p>
110Functions:
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="norma_task_create.html"><strong>norma_task_create</strong></a>,
124<a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>.
125