vm_map

Function - Map the specified memory object to a region of virtual memory.

SYNOPSIS

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);

PARAMETERS

target_task

[in task send right] The port for the task in whose address space the memory object is to be mapped.

address

[pointer to in/out scalar] The starting address for the mapped object. The mapped object will start at the beginning of the page containing address. If there is not enough room following the address, the kernel does not map the object. The kernel returns the starting address actually used for the mapped object.

size

[in scalar] The number of bytes to allocate for the object. The kernel rounds this number up to an integral number of virtual pages.

mask

[in scalar] Alignment restrictions for starting address. Bits turned on in the mask will not be turned on in the starting address.

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.

memory_object

[in memory-object send right] The port naming the memory object. If MEMORY_OBJECT_NULL is specified, the kernel allocates zero-filled memory, as with vm_allocate.

offset

[in scalar] An offset within the memory object, in bytes. The kernel maps address to the specified offset.

copy

[in scalar] Copy indicator. If true, the kernel copies the region of the memory object to the specified task's address space. If false, the region is directly mapped.

cur_protection

[in scalar] The initial current protection for the region. Valid values are obtained by or'ing together the following values:

VM_PROT_READ

Allows read access.

VM_PROT_WRITE

Allows write access.

VM_PROT_EXECUTE

Allows execute access.

max_protection

[in scalar] The maximum protection for the region. Values are the same as for cur_protection.

inheritance

[in scalar] The initial inheritance attribute for the region. Valid values are:

VM_INHERIT_SHARE

Allows child tasks to share the region.

VM_INHERIT_COPY

Gives child tasks a copy of the region.

VM_INHERIT_NONE

Provides no access to the region for child tasks.

DESCRIPTION

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.

RETURN VALUES

KERN_NO_SPACE

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

KERN_PROTECTION_FAILURE

max_protection or cur_protection exceeds that permitted by memory_object.

KERN_INVALID_OBJECT

The memory manager failed to map the memory object.

RELATED INFORMATION

Functions: vm_allocate, vm_remap.