pub struct MmapOptions { /* private fields */ }
Expand description

A memory map builder, providing advanced options and flags for specifying memory map behavior.

MmapOptions can be used to create an anonymous memory map using map_anon(), or a file-backed memory map using one of map(), map_mut(), map_exec(), map_copy(), or map_copy_read_only().

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.

Implementations

Creates a new set of options for configuring and creating a memory map.

Example
use memmap2::{MmapMut, MmapOptions};

// Create a new memory map builder.
let mut mmap_options = MmapOptions::new();

// Configure the memory map builder using option setters, then create
// a memory map using one of `mmap_options.map_anon`, `mmap_options.map`,
// `mmap_options.map_mut`, `mmap_options.map_exec`, or `mmap_options.map_copy`:
let mut mmap: MmapMut = mmap_options.len(36).map_anon()?;

// Use the memory map:
mmap.copy_from_slice(b"...data to copy to the memory map...");

Configures the memory map to start at byte offset from the beginning of the file.

This option has no effect on anonymous memory maps.

By default, the offset is 0.

Example
use memmap2::MmapOptions;
use std::fs::File;

let mmap = unsafe {
    MmapOptions::new()
                .offset(30)
                .map(&File::open("LICENSE-APACHE")?)?
};
assert_eq!(&b"Apache License"[..],
           &mmap[..14]);

Configures the created memory mapped buffer to be len bytes long.

This option is mandatory for anonymous memory maps.

For file-backed memory maps, the length will default to the file length.

Example
use memmap2::MmapOptions;
use std::fs::File;

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

Configures the anonymous memory map to be suitable for a process or thread stack.

This option corresponds to the MAP_STACK flag on Linux. It has no effect on Windows.

This option has no effect on file-backed memory maps.

Example
use memmap2::MmapOptions;

let stack = MmapOptions::new().stack().len(4096).map_anon();

Populate (prefault) page tables for a mapping.

For a file mapping, this causes read-ahead on the file. This will help to reduce blocking on page faults later.

This option corresponds to the MAP_POPULATE flag on Linux. It has no effect on Windows.

Example
use memmap2::MmapOptions;
use std::fs::File;

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

let mmap = unsafe {
    MmapOptions::new().populate().map(&file)?
};

assert_eq!(&b"Copyright"[..], &mmap[..9]);

Creates a read-only memory map backed by a 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 memmap2::MmapOptions;
use std::fs::File;
use std::io::Read;

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

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

let mmap = unsafe {
    MmapOptions::new().map(&file)?
};

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

Creates a readable and executable memory map backed by a 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.

Creates a writeable memory map backed by a 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 and write permissions.

Example
use std::fs::OpenOptions;
use std::path::PathBuf;

use memmap2::MmapOptions;
let path: PathBuf = /* path to file */
let file = OpenOptions::new().read(true).write(true).create(true).open(&path)?;
file.set_len(13)?;

let mut mmap = unsafe {
    MmapOptions::new().map_mut(&file)?
};

mmap.copy_from_slice(b"Hello, world!");

Creates a copy-on-write memory map backed by a file.

Data written to the memory map will not be visible by other processes, and will not be carried through to the underlying 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 writable permissions.

Example
use memmap2::MmapOptions;
use std::fs::File;
use std::io::Write;

let file = File::open("LICENSE-APACHE")?;
let mut mmap = unsafe { MmapOptions::new().map_copy(&file)? };
(&mut mmap[..]).write_all(b"Hello, world!")?;

Creates a copy-on-write read-only memory map backed by a 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 memmap2::MmapOptions;
use std::fs::File;
use std::io::Read;

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

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

let mmap = unsafe {
    MmapOptions::new().map_copy_read_only(&file)?
};

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

Creates an anonymous memory map.

The memory map length should be configured using MmapOptions::len() before creating an anonymous memory map, otherwise a zero-length mapping will be crated.

Errors

This method returns an error when the underlying system call fails or when len > isize::MAX.

Creates a raw memory map.

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 and write permissions.

Trait Implementations

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.