mach/vm_map.h

The vm_region function returns information on a region within the specified task's address space. The function begins looking at address and continues until it finds an allocated region. If the input address is within a region, the function uses the start of that region. The starting address for the located region is returned in address.

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

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.

The vm_deallocate function deallocates a region of virtual memory in the specified task's address space. The region starts at the beginning of the virtual page containing address and ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory deallocated may be greater than size. Use host_page_size to find the current virtual page size. vm_deallocate affects only target_task. Other tasks that have access to the deallocated memory can continue to reference it.

Notes. vm_deallocate can be used to deallocate memory passed as out-of-line data in a message. This interface is machine word length specific because of the virtual address parameter.

The vm_protect function sets access privileges for a region within the specified task's address space. The new_protection parameter specifies a combination of read, write, and execute accesses that are allowed (rather than prohibited). The region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory protected may be greater than size. Use host_page_size to find the current virtual page size. The enforcement of virtual memory protection is machine-dependent. Nominally read access requires VM_PROT_READ permission, write access requires VM_PROT_WRITE permission, and execute access requires VM_PROT_EXECUTE permission. However, some combinations of access rights may not be supported. In particular, the kernel interface allows write access to require VM_PROT_READ and VM_PROT_WRITE permission and execute access to require VM_PROT_READ permission.

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

The vm_inherit function sets the inheritance attribute for a region within the specified task's address space. The inheritance attribute determines the type of access established for child tasks at task creation. Because inheritance applies to virtual pages, the specified address and size are rounded to page boundaries, as follows: the region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size. A parent and a child task can share the same physical memory only if the inheritance for the memory is set to VM_INHERIT_SHARE before the child task is created. Other than through the use of an external memory manager (see vm_map), this is the only way that two tasks can share memory. Note that all the threads within a task share the task's memory.

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

The vm_read and vm_read_overwrite functions read a portion of a task's virtual memory (they enable tasks to read other tasks' memory). The vm_read function returns the data in a dynamically allocated array of bytes; the vm_read_overwrite function places the data into a caller-specified buffer (the data_in parameter).

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

The vm_write function writes an array of data to a task's virtual memory. It allows one task to write to another task's memory. The result of vm_write is as if target_task had directly written into the set of pages. Hence, target_task must have write permission to the pages.

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

The vm_copy function copies a source region to a destination region within the same task's virtual memory. It is semantically equivalent to vm_read followed by vm_write. The destination region can overlap the source region. The destination region must already be allocated. The source region must be readable, and the destination region must be writable.

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

The vm_msync function synchronizes the contents of a memory range with its backing store image by flushing or cleaning the contents of the specified range to the range's memory manager, engaging in a synchronization protocol with the manager (memory_object_synchronize). The client does not return from this call until the memory manager responds (to the kernel) with memory_object_synchronize_completed.

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

The vm_behavior_set function informs the kernel of the expected access pattern for a region of memory. The kernel uses this information to bias its prefetch and page replacement algorithms. The region starts at the beginning of the virtual page containing address; it ends at the end of the virtual page containing address + size - 1. Because of this rounding to virtual page boundaries, the amount of memory affected may be greater than size. Use host_page_size to find the current virtual page size.

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

The vm_map function maps a portion of the specified memory object into the virtual address space belonging to target_task. The target task can be the calling task or another task, identified by its task kernel port. The portion of the memory object mapped is determined by offset and size. The kernel maps address to the offset, so that an access to the memory starts at the offset in the object. The mask parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include: Forcing the memory address alignment for a mapping to be the same as the alignment within the memory object. Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region. Emulating a larger virtual page size. The cur_protection, max_protection, and inheritance parameters set the protection and inheritance attributes for the mapped object. As a rule, at least the maximum protection should be specified so that a server can make a restricted (for example, read-only) mapping in a client atomically. The current protection and inheritance parameters are provided for convenience so that the caller does not have to call vm_inherit and vm_protect separately. The same memory object can be mapped more than once and by more than one task. If an object is mapped by multiple tasks, the kernel maintains consistency for all the mappings if they use the same page alignment for offset and are on the same host. In this case, the virtual memory to which the object is mapped is shared by all the tasks. Changes made by one task in its address space are visible to all the other tasks. The call will not return until the memory object is ready for use.

Notes. vm_map allocates a region in a task's address space and maps the specified memory object to this region. vm_allocate allocates a zero-filled temporary region in a task's address space. Before a memory object can be mapped, a port naming it must be acquired from the memory manager serving it. This interface is machine word length specific because of the virtual address parameter.

Cautions. Do not attempt to map a memory object unless it has been provided by a memory manager that implements the memory object interface. If another type of port is specified, a thread that accesses the mapped virtual memory may become permanently hung or may receive a memory exception.

The vm_machine_attribute function gets and sets special attributes of the memory region implemented by the underlying pmap module. These attributes are properties such as cachability, migratability and replicability. The behavior of this function is machine dependent.

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

The vm_remap function maps the memory objects underlying a portion of the specified source_task 's virtual address space into the address space belonging to target_task. The target task can be the calling task or another task, identified by its task kernel port. The effect is as if the target task performed a vm_map call given the same memory object, maximum protection, current protection, and inheritance as the source task. However, the two tasks must reside on the same host. The kernel maps the memory objects starting at target_address, so that access to target_address is as if the source task accessed its source_address. The mask parameter specifies additional alignment restrictions on the kernel's selection of the starting address. Uses for this mask include: Forcing the memory address alignment for a mapping to be the same as the alignment within the source task. Quickly finding the beginning of an allocated region by performing bit arithmetic on an address known to be in the region. Emulating a larger virtual page size. The cur_protection and max_protection parameters return the protection attributes for the mapped memory. If all memory within the range had the same attributes, these attributes are returned; otherwise the call returns the most restrictive values for any memory in the region.

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