osfmk/man/vm_remap.html

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