osfmk/man/memory_object_lock_request.html
Function - Restrict access to memory object data.
**kern\_return\_t memory\_object\_lock\_request**** (memory\_object\_control\_t **memory\_control,** vm\_offset\_t **offset,** vm\_size\_t **size,** memory\_object\_return\_t **should\_return,** boolean\_t **should\_flush,** vm\_prot\_t **lock\_value,** mach\_port\_t **reply\_port** );**
memory_control[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 memory_object_init call.
offset[in scalar] The offset within the memory object, in bytes.
size[in scalar] The number of bytes of data (starting at offset) to be affected. The number must convert to an integral number of memory object pages.
should_return[in scalar] Clean indicator. Values are:
MEMORY_OBJECT_RETURN_NONE Don't return any pages. If should_flush is TRUE , pages will be discarded.
MEMORY_OBJECT_RETURN_DIRTY Return only dirty (modified) pages. If should_flush is TRUE , precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages.
MEMORY_OBJECT_RETURN_ALL Both dirty and precious pages are returned. If should_flush is FALSE , the kernel maintains responsibility for the precious pages.
MEMORY_OBJECT_RETURN_ANYTHING Any resident pages are returned. If should_flush is TRUE , precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages.
should_flush[in scalar] Flush indicator. If true, the kernel discards all pages within the range.
lock_value[in scalar] One or more forms of access not permitted for the specified data. Valid values are:
VM_PROT_NO_CHANGE Do not change the protection of any pages.
VM_PROT_NONE Prohibits no access (that is, all forms of access are permitted).
VM_PROT_READ Prohibits read access.
VM_PROT_WRITE Prohibits write access.
VM_PROT_EXECUTE Prohibits execute access.
VM_PROT_ALL Prohibits all forms of access.
reply_port[in reply receive (to be converted to send) right] The response port to be used by the kernel on a call to memory_object_lock_completed , or MACH_PORT_NULL if no response is required.
The memory_object_lock_request function allows the memory manager to make the following requests of the kernel:
Clean the pages within the specified range by writing back all changed (that is, dirty) and precious pages. The kernel uses the memory_object_data_return call to write back the data. The should_return parameter must be set to non-zero.
Flush all cached data within the specified range. The kernel invalidates the range of data and revokes all uses of that data. The should_flush parameter must be set to true.
Alter access restrictions specified in the memory_object_data_supply call or a previous memory_object_lock_request call. The lock_value parameter must specify the new access restrictions. Note that this parameter can be used to unlock previously locked data.
Once the kernel performs all of the actions requested by this call, it issues a memory_object_lock_completed call using the reply_to port.
The memory_object_lock_request 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.
When a running thread requires an access that is currently prohibited, the kernel issues a memory_object_data_unlock call specifying the access required. The memory manager can then use memory_object_lock_request to relax its access restrictions on the data.
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 memory_object_data_error.
Only generic errors apply.
Functions: memory_object_data_supply, memory_object_data_unlock, memory_object_lock_completed.