NAME
vm_map - maps a memory object at specified address

SYNOPSIS
kern_return_t vm_map(target_task, address, size, mask, anywhere,
memory_object, offset, copy,
cur_protection, max_protection,
inheritance)
task_t target_task;
vm_offset_t *address; /* in/out */
vm_size_t size;
vm_offset_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;

DESCRIPTION
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. [See the descriptions of
vm_allocate, vm_protect, and vm_inherit.]

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.

ARGUMENTS
target_task Task to be affected.

address Starting address. If the anywhere option is used,
this address is ignored. The address actually
allocated will be returned in address.

size Number of bytes to allocate (rounded by the system
in a machine dependent way).

mask Alignment restriction. Bits asserted in this mask
must not be asserted in the address returned.

anywhere If 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 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.

offset An offset within a memory object, in bytes. The
kernel does not page align this offset.

copy If set, the range of the memory object should be
copied to the target task, rather than mapped read-
write.

DIAGNOSTICS
KERN_SUCCESS The object is mapped.

KERN_NO_SPACE No unused region of the task’s virtual address space
that meets the address, size, and alignment criteria
could be found.

KERN_INVALID_ARGUMENT
An illegal argument was provided.