Crate region[−][src]

Expand description

Cross-platform virtual memory API.

This crate provides a cross-platform Rust API for querying and manipulating virtual memory. It is a thin abstraction, with the underlying interaction implemented using platform specific APIs (e.g VirtualQuery, VirtualLock, mprotect, mlock). Albeit not all OS specific quirks are abstracted away; for instance, some OSs enforce memory pages to be readable, whilst other may prevent pages from becoming executable (i.e DEP).

This implementation operates with memory pages, which are aligned to the operating system’s page size. On some systems, but not all, the system calls for these operations require input to be aligned to a page boundary. To remedy this inconsistency, whenever applicable, input is aligned to its closest page boundary.

Note: a region is a collection of one or more pages laying consecutively in memory, with the same properties.

Parallelism

The properties of virtual memory pages can change at any time, unless all threads that are unaccounted for in a process are stopped. Therefore to obtain, e.g., a true picture of a process’ virtual memory, all other threads must be halted. Otherwise, a region descriptor only represents a snapshot in time.

Installation

This crate is on crates.io and can be used by adding region to your dependencies in your project’s Cargo.toml.

[dependencies]
region = "3.0.0"

Examples

Cross-platform equivalents.

let data = [0xDE, 0xAD, 0xBE, 0xEF];

// Page size
let pz = region::page::size();
let pc = region::page::ceil(data.as_ptr());
let pf = region::page::floor(data.as_ptr());

// VirtualQuery | '/proc/self/maps'
let q  = region::query(data.as_ptr())?;
let qr = region::query_range(data.as_ptr(), data.len())?;

// VirtualAlloc | mmap
let alloc = region::alloc(100, Protection::READ_WRITE)?;

// VirtualProtect | mprotect
region::protect(data.as_ptr(), data.len(), Protection::READ_WRITE_EXECUTE)?;

// ... you can also temporarily change one or more pages' protection
let handle = region::protect_with_handle(data.as_ptr(), data.len(), Protection::READ_WRITE_EXECUTE)?;

// VirtualLock | mlock
let guard = region::lock(data.as_ptr(), data.len())?;