1<h2>vm_remap</h2>
2<hr>
3<p>
4<strong>Function</strong> - Map memory objects in one task's address space to that of another task's.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   vm_remap</strong>
8                 <strong>(mach_port_t</strong>	           <var>target_task</var>,
9                  <strong>vm_address_t</strong>	        <var>target_address</var>,
10                  <strong>vm_size_t</strong>	                  <var>size</var>,
11                  <strong>vm_address_t</strong>	                  <var>mask</var>,
12                  <strong>boolean_t</strong>	              <var>anywhere</var>,
13                  <strong>mach_port_t</strong>	           <var>source_task</var>,
14                  <strong>vm_address_t</strong>	        <var>source_address</var>,
15                  <strong>boolean_t</strong>	                  <var>copy</var>,
16                  <strong>vm_prot_t</strong>	        <var>cur_protection</var>,
17                  <strong>vm_prot_t</strong>	        <var>max_protection</var>,
18                  <strong>vm_inherit_t</strong>            <var>inheritance</var><strong>);</strong>
19</pre>
20<h3>PARAMETERS</h3>
21<dl>
22<dt> <var>target_task</var> 
23<dd>
24[in task send right]
25The port for the task in whose address space the 
26memory is to be mapped.
27     <p>
28<dt> <var>target_address</var> 
29<dd>
30[pointer to in/out scalar]
31The starting address for the mapped memory 
32in the target task.  The mapped memory will start at the beginning of 
33the page containing <var>target_address</var>.  If there is not enough room
34following the address, the kernel does not map the memory.  The kernel
35returns the starting address actually used for the mapped memory.
36     <p>
37<dt> <var>size</var> 
38<dd>
39[in scalar]
40The number of bytes to map.  The kernel rounds this number 
41up to an integral number of virtual pages.
42<p>
43<dt> <var>mask</var> 
44<dd>
45[in scalar]
46Alignment restrictions for starting address.  Bits turned on in 
47the mask will not be turned on in the starting address.
48<p>
49<dt> <var>anywhere</var> 
50<dd>
51[in scalar]
52Placement indicator.
53     The valid values are:
54<dl>
55<p>
56  <dt> <strong>TRUE</strong>
57<dd>
58The kernel allocates the region in the next unused space that 
59is sufficient within the address space.  The kernel returns the 
60starting address actually used in <var>address</var>.
61<p>
62<dt> <strong>FALSE</strong>
63<dd>
64The kernel allocates the region starting at <var>address</var> unless that 
65space is already allocated.
66</dl>
67<p>
68<dt> <var>source_task</var> 
69<dd>
70[in task send right]
71The port for the task whose address space is to be 
72mapped.
73<p>
74<dt> <var>source_address</var> 
75<dd>
76[in scalar]
77The starting address for the memory to be mapped from the 
78source task.  The memory to be mapped will start at the beginning of 
79the page containing <var>source_address</var>.  If not enough memory exists
80following the address, the kernel does not map the memory.
81<p>
82<dt> <var>copy</var> 
83<dd>
84[in scalar]
85Copy indicator.  If true, the kernel copies the region for the 
86memory to the specified task's address space.  If false, the region is 
87mapped read-write.
88<p>
89<dt> <var>cur_protection</var> 
90<dd>
91[out scalar]
92The most restrictive current protection for the memory in 
93the region.  Valid values are obtained by or'ing together the following 
94values:
95<dl>
96<p>
97  <dt> <strong>VM_PROT_READ</strong>
98<dd>
99Allows read access.
100<p>
101<dt> <strong>VM_PROT_WRITE</strong>
102<dd>
103Allows write access.
104<p>
105<dt> <strong>VM_PROT_EXECUTE</strong>
106<dd>
107Allows execute access.
108</dl>
109<p>
110<dt> <var>max_protection</var> 
111<dd>
112[out scalar]
113The most restrictive maximum protection for the memory 
114in the region.  Values are the same as for <var>cur_protection</var>.
115<p>
116<dt> <var>inheritance</var> 
117<dd>
118[in scalar]
119The initial inheritance attribute for the region.  Valid values 
120are:
121<dl>
122<p>
123  <dt> <strong>VM_INHERIT_SHARE</strong>
124<dd>
125Allows child tasks to share the region.
126<p>
127<dt> <strong>VM_INHERIT_COPY</strong>
128<dd>
129Gives child tasks a copy of the region.
130<p>
131<dt> <strong>VM_INHERIT_NONE</strong>
132<dd>
133Provides no access to the region for child tasks.
134</dl>
135</dl>
136<h3>DESCRIPTION</h3>
137<p>
138The <strong>vm_remap</strong> function maps the memory objects underlying
139a portion of the 
140specified <var>source_task</var>'s virtual address space into the address
141space belonging to 
142<var>target_task</var>.  The target task can be the calling task or another
143task, identified by 
144its task kernel port.  The effect is as if the target task performed
145a <strong>vm_map</strong> call 
146given the same memory object, maximum protection, current
147protection, and inheritance as the source task.
148However, the two 
149tasks must reside on the same host.  The kernel maps the memory objects
150starting at <var>target_address</var>, so that access to <var>target_address</var>
151is as if the source task
152accessed its <var>source_address</var>.
153<p>
154The <var>mask</var> parameter 
155specifies additional alignment restrictions on the kernel's 
156selection of the starting address.  Uses for this mask include:
157<ul>
158<li>
159Forcing the memory address alignment for a mapping to be the same as the 
160alignment within the source task.
161<li>
162Quickly finding the beginning of an allocated region by performing bit
163arithmetic on an address known to be in the region.
164<li>
165Emulating a larger virtual page size.
166</ul>
167The <var>cur_protection</var> and <var>max_protection</var> parameters return the protection
168attributes for the mapped memory.  If all memory within the range had the same
169attributes, these attributes are returned; otherwise the call returns the most 
170restrictive values for any memory in the region.
171<h3>NOTES</h3>
172<p>
173This interface is machine word length specific because of the virtual address
174parameter.
175<h3>RETURN VALUES</h3>
176<dl>
177<p>
178  <dt> <strong>KERN_NO_SPACE</strong>
179<dd>
180There is not enough space in the task's address space to allocate the 
181new region for the memory object.
182<p>
183<dt> <strong>KERN_PROTECTION_FAILURE</strong>
184<dd>
185Specified memory is valid, but the backing memory manager is
186not permitted by the requesting task.
187</dl>
188<h3>RELATED INFORMATION</h3>
189<p>
190Functions:
191<a href="vm_map.html"><strong>vm_map</strong></a>,
192<a href="vm_read.html"><strong>vm_read</strong></a>,
193<a href="vm_write.html"><strong>vm_write</strong></a>.
194