Struct mmap_rs::Reserved

pub struct Reserved { /* private fields */ }

Represents an immutable memory mapping in a reserved state, i.e. a memory mapping that is not backed by any physical pages yet.

Implementations

impl Reserved

pub fn is_empty(&self) -> bool

Returns true if the memory mapping is size 0.

pub fn len(&self) -> usize

Yields the length of this mapping.

pub fn make_none(self) -> Result<ReservedNone, (Self, Error)>

Remaps this memory mapping as inaccessible.

In case of failure, this returns the ownership of self. If you are not interested in this feature, you can use the implementation of the TryFrom trait instead.

pub fn make_read_only(self) -> Result<Reserved, (Self, Error)>

Remaps this memory mapping as immutable.

In case of failure, this returns the ownership of self. If you are not interested in this feature, you can use the implementation of the TryFrom trait instead.

pub fn make_exec(self) -> Result<Reserved, (Self, Error)>

Remaps this memory mapping as executable.

In case of failure, this returns the ownership of self.

pub unsafe fn make_exec_no_flush(self) -> Result<Reserved, (Self, Error)>

Remaps this memory mapping as executable, but does not flush the instruction cache.

Safety

While the x86 and x86-64 architectures guarantee cache coherency between the L1 instruction and the L1 data cache, other architectures such as Arm and AArch64 do not. If the user modified the pages, then executing the code may result in undefined behavior. To ensure correct behavior a user has to flush the instruction cache after modifying and before executing the page.

In case of failure, this returns the ownership of self.

pub fn make_mut(self) -> Result<ReservedMut, (Self, Error)>

Remaps this mapping to be mutable.

In case of failure, this returns the ownership of self. If you are not interested in this feature, you can use the implementation of the TryFrom trait instead.

pub unsafe fn make_exec_mut(self) -> Result<ReservedMut, (Self, Error)>

Remaps this mapping to be executable and mutable.

While this may seem useful for self-modifying code and JIT engines, it is instead recommended to convert between mutable and executable mappings using Mmap::make_mut() and MmapMut::make_exec() instead.

Make sure to read the text below to understand the complications of this function before using it. The UnsafeMmapFlags::JIT flag must be set for this function to succeed.

Safety

RWX pages are an interesting targets to attackers, e.g. for buffer overflow attacks, as RWX mappings can potentially simplify such attacks. Without RWX mappings, attackers instead have to resort to return-oriented programming (ROP) gadgets. To prevent buffer overflow attacks, contemporary CPUs allow pages to be marked as non-executable which is then used by the operating system to ensure that pages are either marked as writeable or as executable, but not both. This is also known as W^X.

While the x86 and x86-64 architectures guarantee cache coherency between the L1 instruction and the L1 data cache, other architectures such as Arm and AArch64 do not. If the user modified the pages, then executing the code may result in undefined behavior. To ensure correct behavior a user has to flush the instruction cache after modifying and before executing the page.

In case of failure, this returns the ownership of self.

impl Reserved

pub fn start(&self) -> usize

Returns the start address of this mapping.

pub fn end(&self) -> usize

Returns the end address of this mapping.

pub fn as_ptr(&self) -> *const u8

Yields a raw immutable pointer of this mapping.

pub fn as_mut_ptr(&mut self) -> *mut u8

Yields a raw mutable pointer of this mapping.

pub fn size(&self) -> usize

Yields the size of this mapping.

pub fn merge(&mut self, other: Self) -> Result<(), (Error, Self)>

Merges the memory maps into one. The memory maps must be adjacent to each other and share the same attributes and backing. On success, this consumes the other memory map object. Otherwise, this returns an error together with the original memory map that failed to be merged.

pub fn split_off(&mut self, at: usize) -> Result<Self, Error>

Splits the memory map into two at the given byte offset. The byte offset must be page size aligned.

Afterwards self is limited to the range [0, at), and the returning memory mapping is limited to [at, len).

pub fn split_to(&mut self, at: usize) -> Result<Self, Error>

Splits the memory map into two at the given byte offset. The byte offset must be page size aligned.

Afterwards self is limited to the range [at, len), and the returning memory mapping is limited to [0, at).

Trait Implementations

impl Debug for Reserved

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<Reserved> for Mmap

type Error = Error

The type returned in the event of a conversion error.

fn try_from(reserved: Reserved) -> Result<Mmap, Error>

Performs the conversion.

impl TryFrom<Reserved> for ReservedMut

type Error = Error

The type returned in the event of a conversion error.

fn try_from(mmap: Reserved) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<ReservedMut> for Reserved

type Error = Error

The type returned in the event of a conversion error.

fn try_from(mmap_mut: ReservedMut) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<ReservedNone> for Reserved

type Error = Error

The type returned in the event of a conversion error.

fn try_from(mmap_none: ReservedNone) -> Result<Self, Self::Error>

Performs the conversion.