xnu-1504.3.12.tar.gz

[apple/xnu.git] / osfmk / man / vm_protect.html

<h2>vm_protect</h2>
<hr>
<p>
<strong>Function</strong> - Set access privilege attribute for a region of virtual memory.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   vm_protect</strong>
                 <strong>(vm_task_t</strong>           <var>target_task</var>,
                  <strong>vm_address_t</strong>            <var>address</var>,
                  <strong>vm_size_t</strong>                  <var>size</var>,
                  <strong>boolean_t</strong>           <var>set_maximum</var>,
                  <strong>vm_prot_t</strong>        <var>new_protection</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>target_task</var> 
<dd>
[in task send right]
The port for the task whose address space contains 
the region.
<p>
<dt> <var>address</var> 
<dd>
[in scalar]
The starting address for the region.
<p>
<dt> <var>size</var> 
<dd>
[in scalar]
The number of bytes in the region.
<p>
<dt> <var>set_maximum</var> 
<dd>
[in scalar]
Maximum/current indicator.  If true, the new protection sets 
the maximum protection for the region.  If false, the new protection sets 
the current protection for the region.  If the maximum protection is set 
below the current protection, the current protection is also
     reset to the new 
maximum.
<p>
<dt> <var>new_protection</var> 
<dd>
[in scalar]
The new protection for the region.  Valid values are obtained 
by or'ing together the following values:
<dl>
<p>
<dt> <strong>VM_PROT_READ</strong>
<dd>
Allows read access.
<p>
<dt> <strong>VM_PROT_WRITE</strong>
<dd>
Allows write access.
<p>
<dt> <strong>VM_PROT_EXECUTE</strong>
<dd>
Allows execute access.
</dl>
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>vm_protect</strong> function sets access privileges for
a region within the specified 
task's address space.
The <var>new_protection</var> parameter specifies a combination
of read, write, and 
execute accesses that are allowed (rather than prohibited).
<p>
The region starts at the beginning of the virtual page containing
<var>address</var>; it ends 
at the end of the virtual page containing <var>address</var> + 
<var>size</var> - 1.  Because of this 
rounding to virtual page boundaries, the amount of memory protected may be 
greater than <var>size</var>.  Use <strong>host_page_size</strong> 
to find the current virtual page size.
<p>
The enforcement of virtual memory protection is machine-dependent.
Nominally read access requires <strong>VM_PROT_READ</strong> permission,
write access requires 
<strong>VM_PROT_WRITE</strong> permission, and execute access requires
<strong>VM_PROT_EXECUTE</strong> permission.  However, some combinations
of access rights may not be 
supported.  In particular, the kernel interface allows write access to require 
<strong>VM_PROT_READ</strong> and <strong>VM_PROT_WRITE</strong> permission and execute access to
require <strong>VM_PROT_READ</strong> permission.
<h3>NOTES</h3>
<p>
This interface is machine word length specific because of the virtual address
parameter.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_PROTECTION_FAILURE</strong>
<dd>
The new protection increased the current or maximum protection
beyond the existing maximum protection.
<p>
<dt> <strong>KERN_INVALID_ADDRESS</strong>
<dd>
The address is illegal or specifies a non-allocated region.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="host_page_size.html"><strong>host_page_size</strong></a>,
<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
<a href="vm_region.html"><strong>vm_region</strong></a>.