vm_mapmaps 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_mapcall 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_initcall 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).
vm_mapcall 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_mapcall. 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_SUCCESSif the object is mapped,
KERN_NO_SPACEif no unused region of the task's virtual address space that meets the address, size, and alignment criteria could be found, and
KERN_INVALID_ARGUMENTif an invalid argument was provided.