— Function: kern_return_t vm_map (vm_task_t target_task, vm_address_t *address, vm_size_t size, vm_address_t mask, boolean_t anywhere, memory_object_t memory_object, vm_offset_t offset, boolean_t copy, vm_prot_t cur_protection, vm_prot_t max_protection, vm_inherit_t inheritance)

The function vm_map maps a region of virtual memory at the specified address, for which data is to be supplied by the given memory object, starting at the given offset within that object. In addition to the arguments used in vm_allocate, the vm_map call allows the specification of an address alignment parameter, and of the initial protection and inheritance values.

If the memory object in question is not currently in use, the kernel will perform a memory_object_init call at this time. If the copy parameter is asserted, the specified region of the memory object will be copied to this address space; changes made to this object by other tasks will not be visible in this mapping, and changes made in this mapping will not be visible to others (or returned to the memory object).

The vm_map call returns once the mapping is established. Completion of the call does not require any action on the part of the memory manager.

Warning: Only memory objects that are provided by bona fide memory managers should be used in the vm_map call. A memory manager must implement the memory object interface described elsewhere in this manual. If other ports are used, a thread that accesses the mapped virtual memory may become permanently hung or may receive a memory exception.

target_task is the task to be affected. The starting address is address. If the anywhere option is used, this address is ignored. The address actually allocated will be returned in address. size is the number of bytes to allocate (rounded by the system in a machine dependent way). The alignment restriction is specified by mask. Bits asserted in this mask must not be asserted in the address returned. If anywhere is set, the kernel should find and allocate any region of the specified size, and return the address of the resulting region in address.

memory_object is the port that represents the memory object: used by user tasks in vm_map; used by the make requests for data or other management actions. If this port is MEMORY_OBJECT_NULL, then zero-filled memory is allocated instead. Within a memory object, offset specifies an offset in bytes. This must be page aligned. If copy is set, the range of the memory object should be copied to the target task, rather than mapped read-write.

The function returns KERN_SUCCESS if the object is mapped, KERN_NO_SPACE if no unused region of the task's virtual address space that meets the address, size, and alignment criteria could be found, and KERN_INVALID_ARGUMENT if an invalid argument was provided.