NAME
vm_allocate - allocates virtual memory for a task

SYNOPSIS
#include <mach.h>

kern_return_t vm_allocate(target_task, address, size, anywhere)
vm_task_t target_task;
vm_address_t *address; /* in/out */
vm_size_t size;
boolean_t anywhere;

ARGUMENTS
target_task Task whose virtual address space is to be affected.

address Starting address. If the anywhere option is false,
an attempt is made to allocate virtual memory
starting at this virtual address. If this address is
not at the beginning of a virtual page, it will be
rounded down to one. If there is not enough space at
this address, no memory will be allocated. If the
anywhere option is true, the input value of this
address will be ignored, and the space will be
allocated wherever it is available. In either case,
the address at which memory was actually allocated
will be returned in address.

size Number of bytes to allocate (rounded by the system
in a machine dependent way to an integral number of
virtual pages).

anywhere If true, the kernel should find and allocate any
region of the specified size, and return the address
of the resulting region in address. If false,
virtual memory will be allocated starting at
address, rounded to a virtual page boundary if there
is sufficient space.

DESCRIPTION
vm_allocate allocates a region of virtual memory, placing it in the
specified task’s address space. The physical memory is not
actually allocated until the new virtual memory is referenced. By
default, the kernel rounds all addresses down to the nearest page
boundary and all memory sizes up to the nearest page size. The
global variable vm_page_size contains the page size. task_self_
returns the value of the current task port which should be used as
the target_task argument in order to allocate memory in the
caller’s address space. For languages other than C, these values
can be obtained by the calls vm_statistics and task_self.
Initially, the pages of allocated memory will be protected to allow
all forms of access, and will be inherited in child tasks as a
copy. Subsequent calls to vm_protection and vm_inheritance may be
used to change these properties. The allocated region is always
zero-filled.

DIAGNOSTICS
KERN_SUCCESS Memory allocated.

KERN_INVALID_ADDRESS Illegal address specified.

KERN_NO_SPACE Not enough space left to satisfy this
request

SEE ALSO
vm_deallocate(2), vm_inherit(2), vm_protect(2), vm_regions(2),
vm_statistics(2), task_self_(2)