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