mirror of
https://github.com/darlinghq/darling-xnu.git
synced 2024-11-27 06:20:34 +00:00
107 lines
3.6 KiB
HTML
107 lines
3.6 KiB
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>.
|
|
|