Crate region

source ·
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.2"

§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())?;

Modules§

  • Page related functions.

Structs§

  • A handle to an owned region of memory.
  • A RAII implementation of a scoped lock.
  • A RAII implementation of a scoped protection guard.
  • A bitflag of zero or more protection attributes.
  • An iterator over the Regions that encompass an address range.
  • A descriptor for a mapped memory region.

Enums§

  • A collection of possible errors.

Functions§

  • Allocates one or more pages of memory, with a defined protection.
  • Allocates one or more pages of memory, at a specific address, with a defined protection.
  • Locks one or more memory regions to RAM.
  • Changes the memory protection of one or more pages.
  • Temporarily changes the memory protection of one or more pages.
  • Queries the OS with an address, returning the region it resides within.
  • Queries the OS for mapped regions that overlap with the specified range.
  • Unlocks one or more memory regions from RAM.

Type Aliases§

  • The result type used by this library.