xnu-4903.221.2.tar.gz

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

<h2>vm_allocate</h2>
<hr>
<p>
<strong>Function</strong> - Allocate a region of virtual memory.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   vm_allocate</strong>
                <strong>(vm_task_t</strong>                          <var>target_task</var>,
                 <strong>vm_address_t</strong>                           <var>address</var>,
                 <strong>vm_size_t</strong>                                 <var>size</var>,
                 <strong>boolean_t</strong>                             <var>anywhere</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>target_task</var> 
<dd>
[in task send right]
The port for the task in whose address space the
region is to be allocated.
<p>
<dt> <var>address</var> 
<dd>
[pointer to in/out scalar]
The starting address for the region.  If the
region as specified by the given starting address and size would not lie 
within the task's un-allocated memory, the kernel does not allocate the 
region.  If allocated, the kernel returns the starting address actually used 
for the allocated region.
<p>
<dt> <var>size</var> 
<dd>
[in scalar]
The number of bytes to allocate.
<p>
<dt> <var>anywhere</var> 
<dd>
[in scalar]
Placement indicator. The valid values are:
<dl>
<p>
<dt> <strong>TRUE</strong>
<dd>
The kernel allocates the region in the next unused space that 
is sufficient within the address space.  The kernel returns the 
starting address actually used in <var>address</var>.
<p>
<dt> <strong>FALSE</strong>
<dd>
The kernel allocates the region starting at <var>address</var> unless that 
space is already allocated.
</dl>
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>vm_allocate</strong> function allocates a region of virtual
memory in the specified 
task's address space.  A new region is always zero filled.
<p>
If <var>anywhere</var> is <strong>TRUE</strong>, the returned 
<var>address</var> will be at 
a page boundary; otherwise, the region starts at the beginning
of the virtual page 
containing <var>address</var>.  
<var>size</var> is always rounded up to an integral number of pages. 
Because of this rounding to virtual page boundaries, the amount of memory
allocated may be greater than <var>size</var>.  Use <strong>host_page_size</strong> to find
the current virtual page size.
<p>
Initially, there are no access restrictions on any of the pages of the newly
allocated region.  Child tasks inherit the new region as a copy.
<h3>NOTES</h3>
<p>
To establish different protections or inheritance for the new region, use the
<strong>vm_protect</strong> and <strong>vm_inherit</strong> functions.
<p>
A task's address space can contain both explicitly allocated memory and
automatically allocated memory.  The <strong>vm_allocate</strong> function
explicitly allocates 
memory.  The kernel automatically allocates memory to hold out-of-line data 
passed in a message (and received with <strong>mach_msg</strong>).  The kernel allocates
memory for the passed data as an integral number of pages.
<p>
This interface is machine word length dependent because of the virtual address 
parameter.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_INVALID_ADDRESS</strong>
<dd>
The specified address is illegal or reserved.
<p>
<dt> <strong>KERN_NO_SPACE</strong>
<dd>
There is not enough space in the task's address space to allocate the 
new region.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
<a href="vm_protect.html"><strong>vm_protect</strong></a>,
<a href="vm_region.html"><strong>vm_region</strong></a>,
<a href="host_page_size.html"><strong>host_page_size</strong></a>.