1<h2>memory_object_lock_request</h2>
2<hr>
3<p>
4<strong>Function</strong> - Restrict access to memory object data.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   memory_object_lock_request</strong>
8                <strong>(memory_object_control_t</strong>         <var>memory_control</var>,
9                 <strong>vm_offset_t</strong>                             <var>offset</var>,
10                 <strong>vm_size_t</strong>                                 <var>size</var>,
11                 <strong>memory_object_return_t</strong>           <var>should_return</var>,
12                 <strong>boolean_t</strong>                         <var>should_flush</var>,
13                 <strong>vm_prot_t</strong>                           <var>lock_value</var>,
14                 <strong>mach_port_t</strong>                         <var>reply_port</var><strong>);</strong>
15</pre>
16<h3>PARAMETERS</h3>
17<dl>
18<p>
19<dt> <var>memory_control</var> 
20<dd>
21[in memory-cache-control send right]
22The memory cache control port 
23to be used by the memory manager for cache management requests. 
24This port is provided by the kernel in a <strong>memory_object_init</strong> call.
25<p>
26<dt> <var>offset</var> 
27<dd>
28[in scalar]
29The offset within the memory object, in bytes.
30<p>
31<dt> <var>size</var> 
32<dd>
33[in scalar]
34The number of bytes of data (starting at <var>offset</var>) to be
35affected.  The number must convert to an integral number of memory object 
36pages.
37<p>
38<dt> <var>should_return</var> 
39<dd>
40[in scalar]
41Clean indicator.  Values are:
42<dl>
43<p>
44<dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong>
45<dd>
46Don't return any pages.  If <var>should_flush</var> is <strong>TRUE</strong>, pages will 
47be discarded.
48<p>
49<dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong>
50<dd>
51Return only dirty (modified) pages.  If <var>should_flush</var> is <strong>TRUE</strong>, 
52precious pages will be discarded; otherwise, the kernel
53maintains responsibility for precious pages.
54<p>
55<dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong>
56<dd>
57Both dirty and precious pages are returned.  If <var>should_flush</var> is 
58<strong>FALSE</strong>, the kernel maintains responsibility for the precious 
59pages.
60<p>
61<dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong>
62<dd>
63Any resident pages are returned.   If <var>should_flush</var> is <strong>TRUE</strong>, 
64precious pages will be discarded; otherwise, the kernel
65maintains responsibility for precious pages.
66</dl>
67<p>
68<dt> <var>should_flush</var> 
69<dd>
70[in scalar]
71Flush indicator.  If true, the kernel discards all pages within 
72the range.
73<p>
74<dt> <var>lock_value</var> 
75<dd>
76[in scalar]
77One or more forms of access <var>not</var> permitted for the specified 
78data.  Valid values are:
79<dl>
80<p>
81<dt> <strong>VM_PROT_NO_CHANGE</strong>
82<dd>
83Do not change the protection of any pages.
84<p>
85<dt> <strong>VM_PROT_NONE</strong>
86<dd>
87Prohibits no access (that is, all forms of access are permitted).
88<p>
89<dt> <strong>VM_PROT_READ</strong>
90<dd>
91Prohibits read access.
92<p>
93<dt> <strong>VM_PROT_WRITE</strong>
94<dd>
95Prohibits write access.
96<p>
97<dt> <strong>VM_PROT_EXECUTE</strong>
98<dd>
99Prohibits execute access.
100<p>
101<dt> <strong>VM_PROT_ALL</strong>
102<dd>
103Prohibits all forms of access.
104</dl>
105<p>
106<dt> <var>reply_port</var> 
107<dd>
108[in reply receive (to be converted to send) right]
109The response port to 
110be used by the kernel on a call to <strong>memory_object_lock_completed</strong>, 
111or <strong>MACH_PORT_NULL</strong> if no response is required.
112</dl>
113<h3>DESCRIPTION</h3>
114<p>
115The <strong>memory_object_lock_request</strong> function allows the memory manager to 
116make the following requests of the kernel:
117<ul>
118<li>
119Clean the pages within the specified range by writing back all changed (that 
120is, dirty) and precious pages.  The kernel uses the
121<strong>memory_object_data_return</strong> call to write back the data.
122The <var>should_return</var> parameter must be set to 
123non-zero.
124     <p>
125<li>
126Flush all cached data within the specified range.  The kernel invalidates the 
127range of data and revokes all uses of that data.  The <var>should_flush</var> 
128parameter must be set to true.
129     <p>
130<li>
131Alter access restrictions specified in the <strong>memory_object_data_supply</strong>
132call 
133or a previous <strong>memory_object_lock_request</strong> call.  The
134<var>lock_value</var> parameter 
135must specify the new access restrictions.  Note that this parameter can be 
136used to unlock previously locked data.
137</ul>
138<p>
139Once the kernel performs all of the actions requested by this
140call, it issues a 
141<strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port.
142<h3>NOTES</h3>
143<p>
144The <strong>memory_object_lock_request</strong> call affects only data
145that is cached at the 
146time of the call.  Access restrictions cannot be applied to pages
147for which data 
148has not been provided.
149<p>
150When a running thread requires an access that is currently prohibited,
151the kernel 
152issues a <strong>memory_object_data_unlock</strong> call specifying
153the access required.  The 
154memory manager can then use <strong>memory_object_lock_request</strong> to relax its
155access restrictions on the data.
156<p>
157To indicate that an unlock request is invalid (that is, requires
158permission that can 
159never be granted), the memory manager must first flush the page.  When the
160kernel requests the data again with the higher permission, the
161memory manager can 
162indicate the error by responding with a call to 
163<strong>memory_object_data_error</strong>.
164<h3>RETURN VALUES</h3>
165<p>
166Only generic errors apply.
167<h3>RELATED INFORMATION</h3>
168<p>
169Functions:
170<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
171<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>,
172<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>.
173
174