]> git.saurik.com Git - apple/xnu.git/blame - osfmk/man/vm_allocate.html
xnu-2422.1.72.tar.gz
[apple/xnu.git] / osfmk / man / vm_allocate.html
CommitLineData
13fec989
A
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