— Function: kern_return_t vm_allocate (vm_task_t target_task, vm_address_t *address, vm_size_t size, boolean_t anywhere)

The function vm_allocate allocates a region of virtual memory, placing it in the specified task's address space.

The starting address is 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 is the number of bytes to allocate (rounded by the system in a machine dependent way to an integral number of virtual pages).

If anywhere is true, the kernel should find and allocate any region of the specified size, and return the address of the resulting region in address address, rounded to a virtual page boundary if there is sufficient 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. mach_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 mach_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_protect and vm_inherit may be used to change these properties. The allocated region is always zero-filled.

The function returns KERN_SUCCESS if the memory was successfully allocated, KERN_INVALID_ADDRESS if an invalid address was specified and KERN_NO_SPACE if there was not enough space left to satisfy the request.