Struct memmap2::Mmap

pub struct Mmap { /* fields omitted */ }

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 memmap2::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"# memmap2", &mmap[0..9]);

See MmapMut for the mutable version.

Implementations

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 memmap2::Mmap;

let mut file = File::open("LICENSE-APACHE")?;

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 memmap2::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

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

Performs the conversion.

impl Debug for Mmap

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

Formats the value using the given formatter.

impl Deref for Mmap

type Target = [u8]

The resulting type after dereferencing.

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

Dereferences the value.