Struct memmap2::Mmap [−][src]
pub struct Mmap { /* fields omitted */ }Expand description
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.
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
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[..]);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!")?;