Loading...
--- 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>.
-