osfmk/man/vm_protect.html

   1 <h2>vm_protect</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Set access privilege attribute for a region of virtual memory.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   vm_protect</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>boolean_t</strong>           <var>set_maximum</var>,
  12                   <strong>vm_prot_t</strong>        <var>new_protection</var><strong>);</strong>
  13 </pre>
  14 <h3>PARAMETERS</h3>
  15 <dl>
  16 <p>
  17 <dt> <var>target_task</var>
  18 <dd>
  19 [in task send right]
  20 The port for the task whose address space contains
  21 the region.
  22 <p>
  23 <dt> <var>address</var>
  24 <dd>
  25 [in scalar]
  26 The starting address for the region.
  27 <p>
  28 <dt> <var>size</var>
  29 <dd>
  30 [in scalar]
  31 The number of bytes in the region.
  32 <p>
  33 <dt> <var>set_maximum</var>
  34 <dd>
  35 [in scalar]
  36 Maximum/current indicator.  If true, the new protection sets
  37 the maximum protection for the region.  If false, the new protection sets
  38 the current protection for the region.  If the maximum protection is set
  39 below the current protection, the current protection is also
  40      reset to the new
  41 maximum.
  42 <p>
  43 <dt> <var>new_protection</var>
  44 <dd>
  45 [in scalar]
  46 The new protection for the region.  Valid values are obtained
  47 by or'ing together the following values:
  48 <dl>
  49 <p>
  50 <dt> <strong>VM_PROT_READ</strong>
  51 <dd>
  52 Allows read access.
  53 <p>
  54 <dt> <strong>VM_PROT_WRITE</strong>
  55 <dd>
  56 Allows write access.
  57 <p>
  58 <dt> <strong>VM_PROT_EXECUTE</strong>
  59 <dd>
  60 Allows execute access.
  61 </dl>
  62 </dl>
  63 <h3>DESCRIPTION</h3>
  64 <p>
  65 The <strong>vm_protect</strong> function sets access privileges for
  66 a region within the specified
  67 task's address space.
  68 The <var>new_protection</var> parameter specifies a combination
  69 of read, write, and
  70 execute accesses that are allowed (rather than prohibited).
  71 <p>
  72 The region starts at the beginning of the virtual page containing
  73 <var>address</var>; it ends
  74 at the end of the virtual page containing <var>address</var> +
  75 <var>size</var> - 1.  Because of this
  76 rounding to virtual page boundaries, the amount of memory protected may be
  77 greater than <var>size</var>.  Use <strong>host_page_size</strong>
  78 to find the current virtual page size.
  79 <p>
  80 The enforcement of virtual memory protection is machine-dependent.
  81 Nominally read access requires <strong>VM_PROT_READ</strong> permission,
  82 write access requires
  83 <strong>VM_PROT_WRITE</strong> permission, and execute access requires
  84 <strong>VM_PROT_EXECUTE</strong> permission.  However, some combinations
  85 of access rights may not be
  86 supported.  In particular, the kernel interface allows write access to require
  87 <strong>VM_PROT_READ</strong> and <strong>VM_PROT_WRITE</strong> permission and execute access to
  88 require <strong>VM_PROT_READ</strong> permission.
  89 <h3>NOTES</h3>
  90 <p>
  91 This interface is machine word length specific because of the virtual address
  92 parameter.
  93 <h3>RETURN VALUES</h3>
  94 <dl>
  95 <p>
  96 <dt> <strong>KERN_PROTECTION_FAILURE</strong>
  97 <dd>
  98 The new protection increased the current or maximum protection
  99 beyond the existing maximum protection.
 100 <p>
 101 <dt> <strong>KERN_INVALID_ADDRESS</strong>
 102 <dd>
 103 The address is illegal or specifies a non-allocated region.
 104 </dl>
 105 <h3>RELATED INFORMATION</h3>
 106 <p>
 107 Functions:
 108 <a href="host_page_size.html"><strong>host_page_size</strong></a>,
 109 <a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
 110 <a href="vm_region.html"><strong>vm_region</strong></a>.