vm_allocate

Function - Allocate a region of virtual memory.

SYNOPSIS

kern_return_t   vm_allocate
                (vm_task_t                          target_task,
                 vm_address_t                           address,
                 vm_size_t                                 size,
                 boolean_t                             anywhere);

PARAMETERS

target_task

[in task send right] The port for the task in whose address space the region is to be allocated.

address

[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.

size

[in scalar] The number of bytes to allocate.

anywhere

[in scalar] Placement indicator. The valid values are:

TRUE

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 address.

FALSE

The kernel allocates the region starting at address unless that space is already allocated.

DESCRIPTION

The vm_allocate function allocates a region of virtual memory in the specified task's address space. A new region is always zero filled.

If anywhere is TRUE, the returned address will be at a page boundary; otherwise, the region starts at the beginning of the virtual page containing address. size 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 size. Use host_page_size to find the current virtual page size.

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.

NOTES

To establish different protections or inheritance for the new region, use the vm_protect and vm_inherit functions.

A task's address space can contain both explicitly allocated memory and automatically allocated memory. The vm_allocate function explicitly allocates memory. The kernel automatically allocates memory to hold out-of-line data passed in a message (and received with mach_msg). The kernel allocates memory for the passed data as an integral number of pages.

This interface is machine word length dependent because of the virtual address parameter.

RETURN VALUES

KERN_INVALID_ADDRESS

The specified address is illegal or reserved.

KERN_NO_SPACE

There is not enough space in the task's address space to allocate the new region.

RELATED INFORMATION

Functions: vm_deallocate, vm_inherit, vm_protect, vm_region, host_page_size.