Struct region::View

pub struct View { /* fields omitted */ }

A view aligned to page boundaries.

This view is not aligned to regions, but uses the same granularity as the OSs page size. Therefore it is useful when changing protection, only affecting the pages within the view (instead of entire regions).

Beyond this, it also preserves the previous and initial protection state of all pages within the view. This allows for easily changing states while, still being able to restore them at a later stage.

Implementation

Consider the following 6 pages in memory:

0      4096     8192     12288    16384    20480    24576
+--------+--------+--------+--------+--------+--------+
|  4096  |  4096  |  4096  |  4096  |  4096  |  4096  |
|   RW   |   RX   |   RX   |   RX   |   RX   |   RW   |
+--------+--------+--------+--------+--------+--------+
         |    Region (RX), size of 16 384    |
         +--------+-----------------+--------+
                  | View (len 8192) |
                  +-----------------+

If the view is created with the values:

• address = 8500 (rounded down to the closest page boundary).
• size = 4000 (rounded up to the closest page boundary, relative to the address).

It will contain all pages within the range [8192, 16384), and have a len() of 8192, ignoring the boundaries of the intersecting region.

Examples

use region::{View, Protection};

let ret5 = [0xB8, 0x05, 0x00, 0x00, 0x00, 0xC3];
let mut view = View::new(ret5.as_ptr(), ret5.len()).unwrap();

unsafe {
  view.exec_with_prot(Protection::ReadWriteExecute, || {
    let x: extern "C" fn() -> i32 = unsafe { std::mem::transmute(ret5.as_ptr()) };
    assert_eq!(x(), 5);
  }).unwrap()
}

Methods

impl View

fn new(address: *const u8, size: usize) -> Result<Self>

Constructs a new page view.

The constructor uses query_range internally.

• The address is aligned to the closest page boundary.
• The upper bound (address + size) is rounded up to the closest page boundary.

fn get_prot(&self) -> Option<Flag>

Returns the protection of the pages within the view.

This will only return the protection if all containing pages have the same protection, otherwise None will be returned.

unsafe fn set_prot(&mut self, access: Access) -> Result<()>

Sets the protection of all pages within the view.

Besides applying a new protection state to all pages within the view, this function can also reset the protection of all pages to their initial state (Access::Initial) or their previous state (Access::Previous).

If an access value besides Access::Type is used, it may result in multiple OS calls depending on the number of pages.

unsafe fn exec_with_prot<Ret, T: FnOnce() -> Ret>(
    &mut self,
    prot: Flag,
    callback: T
) -> Result<Ret>

Executes a closure while temporarily changing protection state.

This is a comfortable shorthand method, functionally equivalent to calling set_prot(prot.into()), executing arbitrary code, followed by set_prot(Access::Previous).

fn lock(&mut self) -> Result<LockGuard>

Locks all memory pages within the view.

The view itself does not do any bookkeeping related to whether the pages are locked or not (since the state can change from outside the library).

fn ptr(&self) -> *const u8

Returns the view's base address.

fn mut_ptr(&mut self) -> *mut u8

Returns the view's base address as mutable

fn lower(&self) -> usize

Returns the view's lower bound.

fn upper(&self) -> usize

Returns the view's upper bound.

fn len(&self) -> usize

Returns the length of the view.

fn is_empty(&self) -> bool

Returns whether this view is empty or not.

Trait Implementations

impl Debug for View

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Clone for View

fn clone(&self) -> View

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.