| 9bccf70c |
1 | <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 |
projects / apple / xnu.git / blame