memory_object_lock_request


Function - Restrict access to memory object data.

SYNOPSIS

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);

PARAMETERS

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.

DESCRIPTION

The memory_object_lock_request function allows the memory manager to make the following requests of the kernel:

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.

NOTES

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.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_supply, memory_object_data_unlock, memory_object_lock_completed.