osfmk/man/vm_allocate.html

   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]
  19 The port for the task in whose address space the
  20 region is to be allocated.
  21 <p>
  22 <dt> <var>address</var>
  23 <dd>
  24 [pointer to in/out scalar]
  25 The starting address for the region.  If the
  26 region as specified by the given starting address and size would not lie
  27 within the task's un-allocated memory, the kernel does not allocate the
  28 region.  If allocated, the kernel returns the starting address actually used
  29 for the allocated region.
  30 <p>
  31 <dt> <var>size</var>
  32 <dd>
  33 [in scalar]
  34 The number of bytes to allocate.
  35 <p>
  36 <dt> <var>anywhere</var>
  37 <dd>
  38 [in scalar]
  39 Placement indicator. The valid values are:
  40 <dl>
  41 <p>
  42 <dt> <strong>TRUE</strong>
  43 <dd>
  44 The kernel allocates the region in the next unused space that
  45 is sufficient within the address space.  The kernel returns the
  46 starting address actually used in <var>address</var>.
  47 <p>
  48 <dt> <strong>FALSE</strong>
  49 <dd>
  50 The kernel allocates the region starting at <var>address</var> unless that
  51 space is already allocated.
  52 </dl>
  53 </dl>
  54 <h3>DESCRIPTION</h3>
  55 <p>
  56 The <strong>vm_allocate</strong> function allocates a region of virtual
  57 memory in the specified
  58 task's address space.  A new region is always zero filled.
  59 <p>
  60 If <var>anywhere</var> is <strong>TRUE</strong>, the returned
  61 <var>address</var> will be at
  62 a page boundary; otherwise, the region starts at the beginning
  63 of the virtual page
  64 containing <var>address</var>.
  65 <var>size</var> is always rounded up to an integral number of pages.
  66 Because of this rounding to virtual page boundaries, the amount of memory
  67 allocated may be greater than <var>size</var>.  Use <strong>host_page_size</strong> to find
  68 the current virtual page size.
  69 <p>
  70 Initially, there are no access restrictions on any of the pages of the newly
  71 allocated region.  Child tasks inherit the new region as a copy.
  72 <h3>NOTES</h3>
  73 <p>
  74 To establish different protections or inheritance for the new region, use the
  75 <strong>vm_protect</strong> and <strong>vm_inherit</strong> functions.
  76 <p>
  77 A task's address space can contain both explicitly allocated memory and
  78 automatically allocated memory.  The <strong>vm_allocate</strong> function
  79 explicitly allocates
  80 memory.  The kernel automatically allocates memory to hold out-of-line data
  81 passed in a message (and received with <strong>mach_msg</strong>).  The kernel allocates
  82 memory for the passed data as an integral number of pages.
  83 <p>
  84 This interface is machine word length dependent because of the virtual address
  85 parameter.
  86 <h3>RETURN VALUES</h3>
  87 <dl>
  88 <p>
  89 <dt> <strong>KERN_INVALID_ADDRESS</strong>
  90 <dd>
  91 The specified address is illegal or reserved.
  92 <p>
  93 <dt> <strong>KERN_NO_SPACE</strong>
  94 <dd>
  95 There is not enough space in the task's address space to allocate the
  96 new region.
  97 </dl>
  98 <h3>RELATED INFORMATION</h3>
  99 <p>
 100 Functions:
 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