1<h2>vm_map</h2>
2<hr>
3<p>
4<strong>Function</strong> - Map the specified memory object to a region of virtual memory.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   vm_map</strong>
8                <strong>(vm_task_t</strong>                          <var>target_task</var>,
9                 <strong>vm_address_t</strong>                           <var>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>memory_object_t</strong>                  <var>memory_object</var>,
14                 <strong>vm_offset_t</strong>                             <var>offset</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<p>
23<dt> <var>target_task</var> 
24<dd>
25[in task send right]
26The port for the task in whose address space the 
27memory object is to be mapped.
28<p>
29<dt> <var>address</var> 
30<dd>
31[pointer to in/out scalar]
32The starting address for the mapped object. 
33The mapped object will start at the beginning of the page containing 
34<var>address</var>.  If there is not enough room following the address, the kernel 
35does not map the object.  The kernel returns the starting address
36actually used for the mapped object.
37<p>
38<dt> <var>size</var> 
39<dd>
40[in scalar]
41The number of bytes to allocate for the object.  The kernel 
42rounds this number up to an integral number of virtual pages.
43<p>
44<dt> <var>mask</var> 
45<dd>
46[in scalar]
47Alignment restrictions for starting address.  Bits turned on in 
48the mask will not be turned on in the starting address.
49<p>
50<dt> <var>anywhere</var> 
51<dd>
52[in scalar]
53Placement indicator.  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>memory_object</var> 
69<dd>
70[in memory-object send right]
71The port naming the 
72memory object.  If <strong>MEMORY_OBJECT_NULL</strong> is
73specified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>.
74<p>
75<dt> <var>offset</var> 
76<dd>
77[in scalar]
78An offset within the memory object, in bytes.  The kernel 
79maps <var>address</var> to the specified offset.
80<p>
81<dt> <var>copy</var> 
82<dd>
83[in scalar]
84Copy indicator.  If true, the kernel copies the region of the 
85memory object to the specified task's address space.  If false, the region 
86is directly mapped.
87<p>
88<dt> <var>cur_protection</var> 
89<dd>
90[in scalar]
91The initial current protection for the region.  Valid values are 
92obtained by or'ing together the following values:
93<dl>
94<p>
95<dt> <strong>VM_PROT_READ</strong>
96<dd>
97Allows read access.
98<p>
99<dt> <strong>VM_PROT_WRITE</strong>
100<dd>
101Allows write access.
102<p>
103<dt> <strong>VM_PROT_EXECUTE</strong>
104<dd>
105Allows execute access.
106</dl>
107<p>
108<dt> <var>max_protection</var> 
109<dd>
110[in scalar]
111The maximum protection for the region.  Values are the same 
112as for <var>cur_protection</var>.
113<p>
114<dt> <var>inheritance</var> 
115<dd>
116[in scalar]
117The initial inheritance attribute for the region.  Valid values 
118are:
119<dl>
120<p>
121<dt> <strong>VM_INHERIT_SHARE</strong>
122<dd>
123Allows child tasks to share the region.
124<p>
125<dt> <strong>VM_INHERIT_COPY</strong>
126<dd>
127Gives child tasks a copy of the region.
128<p>
129<dt> <strong>VM_INHERIT_NONE</strong>
130<dd>
131Provides no access to the region for child tasks.
132</dl>
133</dl>
134<h3>DESCRIPTION</h3>
135<p>
136The <strong>vm_map</strong> function maps a portion of the specified
137memory object into the 
138virtual address space belonging to <var>target_task</var>.  The target task
139can be the calling 
140task or another task, identified by its task kernel port.
141<p>
142The portion of the memory object mapped is determined by <var>offset</var> 
143and <var>size</var>.  The 
144kernel maps <var>address</var> to the offset, so that an access to the memory
145starts at the offset in the object.
146<p>
147The <var>mask</var> parameter specifies additional alignment restrictions on 
148the kernel's selection of the starting address.  Uses for this mask include:
149<ul>
150<li>
151Forcing the memory address alignment for a mapping to be the same as the 
152alignment within the memory object.
153<li>
154Quickly finding the beginning of an allocated region by performing bit
155arithmetic on an address known to be in the region.
156<li>
157Emulating a larger virtual page size.
158</ul>
159<p>
160The <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var>
161parameters set the
162protection and inheritance attributes for the mapped object.
163As a rule, at least the
164maximum protection should be specified so that a server can make
165a restricted (for 
166example, read-only) mapping in a client atomically.  The current
167protection and 
168inheritance parameters are provided for convenience so that the
169caller does not 
170have to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately.
171<p>
172The same memory object can be mapped more than once and by more than one 
173task.  If an object is mapped by multiple tasks, the kernel maintains
174consistency 
175for all the mappings if they use the same page alignment for <var>offset</var> 
176and are on 
177the same host.  In this case, the virtual memory to which the
178object is mapped is 
179shared by all the tasks.  Changes made by one task in its address space are
180visible to all the other tasks.
181The call will not return until the
182memory object is ready for 
183use.
184<h3>NOTES</h3>
185<p>
186<strong>vm_map</strong> allocates a region in a task's address space
187and maps the specified 
188memory object to this region.  <strong>vm_allocate</strong> allocates
189a zero-filled temporary
190region in a task's address space.
191<p>
192Before a memory object can be mapped, a port naming it must be acquired from 
193the memory manager serving it.
194<p>
195This interface is machine word length specific because of the virtual address
196parameter.
197<h3>CAUTIONS</h3>
198<p>
199Do not attempt to map a memory object unless it has been provided by a
200memory manager that implements the memory object interface. 
201If another type of port 
202is specified, a thread that accesses the mapped virtual memory may become
203permanently hung or may receive a memory exception.
204<h3>RETURN VALUES</h3>
205<dl>
206<p>
207<dt> <strong>KERN_NO_SPACE</strong>
208<dd>
209There is not enough space in the task's address space to allocate the 
210new region for the memory object.
211<p>
212<dt> <strong>KERN_PROTECTION_FAILURE</strong>
213<dd>
214<var>max_protection</var> or <var>cur_protection</var> exceeds 
215that permitted by <var>memory_object</var>.
216<p>
217<dt> <strong>KERN_INVALID_OBJECT</strong>
218<dd>
219The memory manager failed to map the memory object.
220</dl>
221<h3>RELATED INFORMATION</h3>
222<p>
223Functions:
224<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
225<a href="vm_remap.html"><strong>vm_remap</strong></a>.
226