-<h2>vm_allocate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Allocate a region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_allocate</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>boolean_t</strong> <var>anywhere</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rregion is to be allocated.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[pointer to in/out scalar]
\rThe starting address for the region. If the
\rregion as specified by the given starting address and size would not lie
\rwithin the task's un-allocated memory, the kernel does not allocate the
\rregion. If allocated, the kernel returns the starting address actually used
\rfor the allocated region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to allocate.
\r<p>
\r<dt> <var>anywhere</var>
\r<dd>
\r[in scalar]
\rPlacement indicator. The valid values are:
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe kernel allocates the region in the next unused space that
\ris sufficient within the address space. The kernel returns the
\rstarting address actually used in <var>address</var>.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe kernel allocates the region starting at <var>address</var> unless that
\rspace is already allocated.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_allocate</strong> function allocates a region of virtual
\rmemory in the specified
\rtask's address space. A new region is always zero filled.
\r<p>
\rIf <var>anywhere</var> is <strong>TRUE</strong>, the returned
\r<var>address</var> will be at
\ra page boundary; otherwise, the region starts at the beginning
\rof the virtual page
\rcontaining <var>address</var>.
\r<var>size</var> is always rounded up to an integral number of pages.
\rBecause of this rounding to virtual page boundaries, the amount of memory
\rallocated may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find
\rthe current virtual page size.
\r<p>
\rInitially, there are no access restrictions on any of the pages of the newly
\rallocated region. Child tasks inherit the new region as a copy.
\r<h3>NOTES</h3>
\r<p>
\rTo establish different protections or inheritance for the new region, use the
\r<strong>vm_protect</strong> and <strong>vm_inherit</strong> functions.
\r<p>
\rA task's address space can contain both explicitly allocated memory and
\rautomatically allocated memory. The <strong>vm_allocate</strong> function
\rexplicitly allocates
\rmemory. The kernel automatically allocates memory to hold out-of-line data
\rpassed in a message (and received with <strong>mach_msg</strong>). The kernel allocates
\rmemory for the passed data as an integral number of pages.
\r<p>
\rThis interface is machine word length dependent because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe specified address is illegal or reserved.
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere is not enough space in the task's address space to allocate the
\rnew region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
\r<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
\r<a href="vm_protect.html"><strong>vm_protect</strong></a>,
\r<a href="vm_region.html"><strong>vm_region</strong></a>,
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>.
\r\r\ No newline at end of file
+<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>.
+
projects / apple / xnu.git / blobdiff