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