Loading...
osfmk/man/memory_object_lock_request.html xnu-792 /dev/null
--- xnu/xnu-792/osfmk/man/memory_object_lock_request.html
+++ /dev/null
@@ -1,173 +0,0 @@
-<h2>memory_object_lock_request</h2>
-<hr>
-<p>
-<strong>Function</strong> - Restrict access to memory object data.
-<h3>SYNOPSIS</h3>
-<pre>
-<strong>kern_return_t   memory_object_lock_request</strong>
-                <strong>(memory_object_control_t</strong>         <var>memory_control</var>,
-                 <strong>vm_offset_t</strong>                             <var>offset</var>,
-                 <strong>vm_size_t</strong>                                 <var>size</var>,
-                 <strong>memory_object_return_t</strong>           <var>should_return</var>,
-                 <strong>boolean_t</strong>                         <var>should_flush</var>,
-                 <strong>vm_prot_t</strong>                           <var>lock_value</var>,
-                 <strong>mach_port_t</strong>                         <var>reply_port</var><strong>);</strong>
-</pre>
-<h3>PARAMETERS</h3>
-<dl>
-<p>
-<dt> <var>memory_control</var> 
-<dd>
-[in memory-cache-control send right]
-The memory cache control port 
-to be used by the memory manager for cache management requests. 
-This port is provided by the kernel in a <strong>memory_object_init</strong> call.
-<p>
-<dt> <var>offset</var> 
-<dd>
-[in scalar]
-The offset within the memory object, in bytes.
-<p>
-<dt> <var>size</var> 
-<dd>
-[in scalar]
-The number of bytes of data (starting at <var>offset</var>) to be
-affected.  The number must convert to an integral number of memory object 
-pages.
-<p>
-<dt> <var>should_return</var> 
-<dd>
-[in scalar]
-Clean indicator.  Values are:
-<dl>
-<p>
-<dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong>
-<dd>
-Don't return any pages.  If <var>should_flush</var> is <strong>TRUE</strong>, pages will 
-be discarded.
-<p>
-<dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong>
-<dd>
-Return only dirty (modified) pages.  If <var>should_flush</var> is <strong>TRUE</strong>, 
-precious pages will be discarded; otherwise, the kernel
-maintains responsibility for precious pages.
-<p>
-<dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong>
-<dd>
-Both dirty and precious pages are returned.  If <var>should_flush</var> is 
-<strong>FALSE</strong>, the kernel maintains responsibility for the precious 
-pages.
-<p>
-<dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong>
-<dd>
-Any resident pages are returned.   If <var>should_flush</var> is <strong>TRUE</strong>, 
-precious pages will be discarded; otherwise, the kernel
-maintains responsibility for precious pages.
-</dl>
-<p>
-<dt> <var>should_flush</var> 
-<dd>
-[in scalar]
-Flush indicator.  If true, the kernel discards all pages within 
-the range.
-<p>
-<dt> <var>lock_value</var> 
-<dd>
-[in scalar]
-One or more forms of access <var>not</var> permitted for the specified 
-data.  Valid values are:
-<dl>
-<p>
-<dt> <strong>VM_PROT_NO_CHANGE</strong>
-<dd>
-Do not change the protection of any pages.
-<p>
-<dt> <strong>VM_PROT_NONE</strong>
-<dd>
-Prohibits no access (that is, all forms of access are permitted).
-<p>
-<dt> <strong>VM_PROT_READ</strong>
-<dd>
-Prohibits read access.
-<p>
-<dt> <strong>VM_PROT_WRITE</strong>
-<dd>
-Prohibits write access.
-<p>
-<dt> <strong>VM_PROT_EXECUTE</strong>
-<dd>
-Prohibits execute access.
-<p>
-<dt> <strong>VM_PROT_ALL</strong>
-<dd>
-Prohibits all forms of access.
-</dl>
-<p>
-<dt> <var>reply_port</var> 
-<dd>
-[in reply receive (to be converted to send) right]
-The response port to 
-be used by the kernel on a call to <strong>memory_object_lock_completed</strong>, 
-or <strong>MACH_PORT_NULL</strong> if no response is required.
-</dl>
-<h3>DESCRIPTION</h3>
-<p>
-The <strong>memory_object_lock_request</strong> function allows the memory manager to 
-make the following requests of the kernel:
-<ul>
-<li>
-Clean the pages within the specified range by writing back all changed (that 
-is, dirty) and precious pages.  The kernel uses the
-<strong>memory_object_data_return</strong> call to write back the data.
-The <var>should_return</var> parameter must be set to 
-non-zero.
-     <p>
-<li>
-Flush all cached data within the specified range.  The kernel invalidates the 
-range of data and revokes all uses of that data.  The <var>should_flush</var> 
-parameter must be set to true.
-     <p>
-<li>
-Alter access restrictions specified in the <strong>memory_object_data_supply</strong>
-call 
-or a previous <strong>memory_object_lock_request</strong> call.  The
-<var>lock_value</var> parameter 
-must specify the new access restrictions.  Note that this parameter can be 
-used to unlock previously locked data.
-</ul>
-<p>
-Once the kernel performs all of the actions requested by this
-call, it issues a 
-<strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port.
-<h3>NOTES</h3>
-<p>
-The <strong>memory_object_lock_request</strong> call affects only data
-that is cached at the 
-time of the call.  Access restrictions cannot be applied to pages
-for which data 
-has not been provided.
-<p>
-When a running thread requires an access that is currently prohibited,
-the kernel 
-issues a <strong>memory_object_data_unlock</strong> call specifying
-the access required.  The 
-memory manager can then use <strong>memory_object_lock_request</strong> to relax its
-access restrictions on the data.
-<p>
-To indicate that an unlock request is invalid (that is, requires
-permission that can 
-never be granted), the memory manager must first flush the page.  When the
-kernel requests the data again with the higher permission, the
-memory manager can 
-indicate the error by responding with a call to 
-<strong>memory_object_data_error</strong>.
-<h3>RETURN VALUES</h3>
-<p>
-Only generic errors apply.
-<h3>RELATED INFORMATION</h3>
-<p>
-Functions:
-<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
-<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>,
-<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>.
-