vm_remap

Function - Map memory objects in one task's address space to that of another task's.

SYNOPSIS

kern_return_t   vm_remap
                 (mach_port_t	           target_task,
                  vm_address_t	        target_address,
                  vm_size_t	                  size,
                  vm_address_t	                  mask,
                  boolean_t	              anywhere,
                  mach_port_t	           source_task,
                  vm_address_t	        source_address,
                  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 is to be mapped.

target_address

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

size

[in scalar] The number of bytes to map. 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.

source_task

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

source_address

[in scalar] The starting address for the memory to be mapped from the source task. The memory to be mapped will start at the beginning of the page containing source_address. If not enough memory exists following the address, the kernel does not map the memory.

copy

[in scalar] Copy indicator. If true, the kernel copies the region for the memory to the specified task's address space. If false, the region is mapped read-write.

cur_protection

[out scalar] The most restrictive current protection for the memory in 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

[out scalar] The most restrictive maximum protection for the memory in 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_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.

NOTES

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

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

Specified memory is valid, but the backing memory manager is not permitted by the requesting task.

RELATED INFORMATION

Functions: vm_map, vm_read, vm_write.