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

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