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 107