xnu-4903.221.2.tar.gz

[apple/xnu.git] / osfmk / man / vm_remap.html

<h2>vm_remap</h2>
<hr>
<p>
<strong>Function</strong> - Map memory objects in one task's address space to that of another task's.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   vm_remap</strong>
                 <strong>(mach_port_t</strong>	           <var>target_task</var>,
                  <strong>vm_address_t</strong>	        <var>target_address</var>,
                  <strong>vm_size_t</strong>	                  <var>size</var>,
                  <strong>vm_address_t</strong>	                  <var>mask</var>,
                  <strong>boolean_t</strong>	              <var>anywhere</var>,
                  <strong>mach_port_t</strong>	           <var>source_task</var>,
                  <strong>vm_address_t</strong>	        <var>source_address</var>,
                  <strong>boolean_t</strong>	                  <var>copy</var>,
                  <strong>vm_prot_t</strong>	        <var>cur_protection</var>,
                  <strong>vm_prot_t</strong>	        <var>max_protection</var>,
                  <strong>vm_inherit_t</strong>            <var>inheritance</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<dt> <var>target_task</var> 
<dd>
[in task send right]
The port for the task in whose address space the 
memory is to be mapped.
     <p>
<dt> <var>target_address</var> 
<dd>
[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 <var>target_address</var>.  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.
     <p>
<dt> <var>size</var> 
<dd>
[in scalar]
The number of bytes to map.  The kernel rounds this number 
up to an integral number of virtual pages.
<p>
<dt> <var>mask</var> 
<dd>
[in scalar]
Alignment restrictions for starting address.  Bits turned on in 
the mask will not be turned on in the starting address.
<p>
<dt> <var>anywhere</var> 
<dd>
[in scalar]
Placement indicator.
     The valid values are:
<dl>
<p>
  <dt> <strong>TRUE</strong>
<dd>
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 <var>address</var>.
<p>
<dt> <strong>FALSE</strong>
<dd>
The kernel allocates the region starting at <var>address</var> unless that 
space is already allocated.
</dl>
<p>
<dt> <var>source_task</var> 
<dd>
[in task send right]
The port for the task whose address space is to be 
mapped.
<p>
<dt> <var>source_address</var> 
<dd>
[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 <var>source_address</var>.  If not enough memory exists
following the address, the kernel does not map the memory.
<p>
<dt> <var>copy</var> 
<dd>
[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.
<p>
<dt> <var>cur_protection</var> 
<dd>
[out scalar]
The most restrictive current protection for the memory in 
the region.  Valid values are obtained by or'ing together the following 
values:
<dl>
<p>
  <dt> <strong>VM_PROT_READ</strong>
<dd>
Allows read access.
<p>
<dt> <strong>VM_PROT_WRITE</strong>
<dd>
Allows write access.
<p>
<dt> <strong>VM_PROT_EXECUTE</strong>
<dd>
Allows execute access.
</dl>
<p>
<dt> <var>max_protection</var> 
<dd>
[out scalar]
The most restrictive maximum protection for the memory 
in the region.  Values are the same as for <var>cur_protection</var>.
<p>
<dt> <var>inheritance</var> 
<dd>
[in scalar]
The initial inheritance attribute for the region.  Valid values 
are:
<dl>
<p>
  <dt> <strong>VM_INHERIT_SHARE</strong>
<dd>
Allows child tasks to share the region.
<p>
<dt> <strong>VM_INHERIT_COPY</strong>
<dd>
Gives child tasks a copy of the region.
<p>
<dt> <strong>VM_INHERIT_NONE</strong>
<dd>
Provides no access to the region for child tasks.
</dl>
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>vm_remap</strong> function maps the memory objects underlying
a portion of the 
specified <var>source_task</var>'s virtual address space into the address
space belonging to 
<var>target_task</var>.  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 <strong>vm_map</strong> 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 <var>target_address</var>, so that access to <var>target_address</var>
is as if the source task
accessed its <var>source_address</var>.
<p>
The <var>mask</var> parameter 
specifies additional alignment restrictions on the kernel's 
selection of the starting address.  Uses for this mask include:
<ul>
<li>
Forcing the memory address alignment for a mapping to be the same as the 
alignment within the source task.
<li>
Quickly finding the beginning of an allocated region by performing bit
arithmetic on an address known to be in the region.
<li>
Emulating a larger virtual page size.
</ul>
The <var>cur_protection</var> and <var>max_protection</var> 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.
<h3>NOTES</h3>
<p>
This interface is machine word length specific because of the virtual address
parameter.
<h3>RETURN VALUES</h3>
<dl>
<p>
  <dt> <strong>KERN_NO_SPACE</strong>
<dd>
There is not enough space in the task's address space to allocate the 
new region for the memory object.
<p>
<dt> <strong>KERN_PROTECTION_FAILURE</strong>
<dd>
Specified memory is valid, but the backing memory manager is
not permitted by the requesting task.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="vm_map.html"><strong>vm_map</strong></a>,
<a href="vm_read.html"><strong>vm_read</strong></a>,
<a href="vm_write.html"><strong>vm_write</strong></a>.