Struct memmap::Mmap

pub struct Mmap {
    inner: MmapInner,
}

A handle to an immutable memory mapped buffer.

A Mmap may be backed by a file, or it can be anonymous map, backed by volatile memory. Use [MmapOptions] or map() to create a file-backed memory map. To create an immutable anonymous memory map, first create a mutable anonymous memory map, and then make it immutable with [MmapMut::make_read_only()].

A file backed Mmap is created by &File reference, and will remain valid even after the File is dropped. In other words, the Mmap handle is completely independent of the File used to create it. For consistency, on some platforms this is achieved by duplicating the underlying file handle. The memory will be unmapped when the Mmap handle is dropped.

Dereferencing and accessing the bytes of the buffer may result in page faults (e.g. swapping the mapped pages into physical memory) though the details of this are platform specific.

Mmap is Sync and Send.

Safety

All file-backed memory map constructors are marked unsafe because of the potential for Undefined Behavior (UB) using the map if the underlying file is subsequently modified, in or out of process. Applications must consider the risk and take appropriate precautions when using file-backed maps. Solutions such as file permissions, locks or process-private (e.g. unlinked) files exist but are platform specific and limited.

Example

use memmap::MmapOptions;
use std::io::Write;
use std::fs::File;

let file = File::open("README.md")?;
let mmap = unsafe { MmapOptions::new().map(&file)? };
assert_eq!(b"# memmap", &mmap[0..8]);

See [MmapMut] for the mutable version.

Fields

inner: MmapInner

Methods

impl Mmap

pub unsafe fn map(file: &File) -> Result<Mmap>

Creates a read-only memory map backed by a file.

This is equivalent to calling MmapOptions::new().map(file).

Errors

This method returns an error when the underlying system call fails, which can happen for a variety of reasons, such as when the file is not open with read permissions.

Example

use std::fs::File;
use std::io::Read;

use memmap::Mmap;

let mut file = File::open("README.md")?;

let mut contents = Vec::new();
file.read_to_end(&mut contents)?;

let mmap = unsafe { Mmap::map(&file)?  };

assert_eq!(&contents[..], &mmap[..]);

pub fn make_mut(self) -> Result<MmapMut>

Transition the memory map to be writable.

If the memory map is file-backed, the file must have been opened with write permissions.

Errors

This method returns an error when the underlying system call fails, which can happen for a variety of reasons, such as when the file is not open with writable permissions.

Example

use memmap::Mmap;
use std::ops::DerefMut;
use std::io::Write;

let file = /* file opened with write permissions */
let mmap = unsafe { Mmap::map(&file)? };
// ... use the read-only memory map ...
let mut mut_mmap = mmap.make_mut()?;
mut_mmap.deref_mut().write_all(b"hello, world!")?;

Trait Implementations

impl AsRef<[u8]> for Mmap

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl Deref for Mmap

type Target = [u8]

The resulting type after dereferencing.

fn deref(&self) -> &[u8]

Dereferences the value.

impl Debug for Mmap

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

Formats the value using the given formatter.