1<h2>vm_allocate</h2>
2<hr>
3<p>
4<strong>Function</strong> - Allocate a region of virtual memory.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   vm_allocate</strong>
8                <strong>(vm_task_t</strong>                          <var>target_task</var>,
9                 <strong>vm_address_t</strong>                           <var>address</var>,
10                 <strong>vm_size_t</strong>                                 <var>size</var>,
11                 <strong>boolean_t</strong>                             <var>anywhere</var><strong>);</strong>
12</pre>
13<h3>PARAMETERS</h3>
14<dl>
15<p>
16<dt> <var>target_task</var> 
17<dd>
18[in task send right]
19The port for the task in whose address space the
20region is to be allocated.
21<p>
22<dt> <var>address</var> 
23<dd>
24[pointer to in/out scalar]
25The starting address for the region.  If the
26region as specified by the given starting address and size would not lie 
27within the task's un-allocated memory, the kernel does not allocate the 
28region.  If allocated, the kernel returns the starting address actually used 
29for the allocated region.
30<p>
31<dt> <var>size</var> 
32<dd>
33[in scalar]
34The number of bytes to allocate.
35<p>
36<dt> <var>anywhere</var> 
37<dd>
38[in scalar]
39Placement indicator. The valid values are:
40<dl>
41<p>
42<dt> <strong>TRUE</strong>
43<dd>
44The kernel allocates the region in the next unused space that 
45is sufficient within the address space.  The kernel returns the 
46starting address actually used in <var>address</var>.
47<p>
48<dt> <strong>FALSE</strong>
49<dd>
50The kernel allocates the region starting at <var>address</var> unless that 
51space is already allocated.
52</dl>
53</dl>
54<h3>DESCRIPTION</h3>
55<p>
56The <strong>vm_allocate</strong> function allocates a region of virtual
57memory in the specified 
58task's address space.  A new region is always zero filled.
59<p>
60If <var>anywhere</var> is <strong>TRUE</strong>, the returned 
61<var>address</var> will be at 
62a page boundary; otherwise, the region starts at the beginning
63of the virtual page 
64containing <var>address</var>.  
65<var>size</var> is always rounded up to an integral number of pages. 
66Because of this rounding to virtual page boundaries, the amount of memory
67allocated may be greater than <var>size</var>.  Use <strong>host_page_size</strong> to find
68the current virtual page size.
69<p>
70Initially, there are no access restrictions on any of the pages of the newly
71allocated region.  Child tasks inherit the new region as a copy.
72<h3>NOTES</h3>
73<p>
74To establish different protections or inheritance for the new region, use the
75<strong>vm_protect</strong> and <strong>vm_inherit</strong> functions.
76<p>
77A task's address space can contain both explicitly allocated memory and
78automatically allocated memory.  The <strong>vm_allocate</strong> function
79explicitly allocates 
80memory.  The kernel automatically allocates memory to hold out-of-line data 
81passed in a message (and received with <strong>mach_msg</strong>).  The kernel allocates
82memory for the passed data as an integral number of pages.
83<p>
84This interface is machine word length dependent because of the virtual address 
85parameter.
86<h3>RETURN VALUES</h3>
87<dl>
88<p>
89<dt> <strong>KERN_INVALID_ADDRESS</strong>
90<dd>
91The specified address is illegal or reserved.
92<p>
93<dt> <strong>KERN_NO_SPACE</strong>
94<dd>
95There is not enough space in the task's address space to allocate the 
96new region.
97</dl>
98<h3>RELATED INFORMATION</h3>
99<p>
100Functions:
101<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
102<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
103<a href="vm_protect.html"><strong>vm_protect</strong></a>,
104<a href="vm_region.html"><strong>vm_region</strong></a>,
105<a href="host_page_size.html"><strong>host_page_size</strong></a>.
106
107