Struct memmap2::MmapOptions [−][src]
pub struct MmapOptions { /* fields omitted */ }
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
impl MmapOptions
[src]
impl MmapOptions
[src]pub fn new() -> MmapOptions
[src]
pub fn new() -> MmapOptions
[src]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...");
pub fn offset(&mut self, offset: u64) -> &mut Self
[src]
pub fn offset(&mut self, offset: u64) -> &mut Self
[src]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]);
pub fn len(&mut self, len: usize) -> &mut Self
[src]
pub fn len(&mut self, len: usize) -> &mut Self
[src]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[..]);
pub fn stack(&mut self) -> &mut Self
[src]
pub fn stack(&mut self) -> &mut Self
[src]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();
pub fn populate(&mut self) -> &mut Self
[src]
pub fn populate(&mut self) -> &mut Self
[src]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]);
pub unsafe fn map(&self, file: &File) -> Result<Mmap>
[src]
pub unsafe fn map(&self, file: &File) -> Result<Mmap>
[src]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[..]);
pub unsafe fn map_exec(&self, file: &File) -> Result<Mmap>
[src]
pub unsafe fn map_exec(&self, file: &File) -> Result<Mmap>
[src]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.
pub unsafe fn map_mut(&self, file: &File) -> Result<MmapMut>
[src]
pub unsafe fn map_mut(&self, file: &File) -> Result<MmapMut>
[src]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!");
pub unsafe fn map_copy(&self, file: &File) -> Result<MmapMut>
[src]
pub unsafe fn map_copy(&self, file: &File) -> Result<MmapMut>
[src]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!")?;
pub unsafe fn map_copy_read_only(&self, file: &File) -> Result<Mmap>
[src]
pub unsafe fn map_copy_read_only(&self, file: &File) -> Result<Mmap>
[src]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[..]);
Trait Implementations
impl Clone for MmapOptions
[src]
impl Clone for MmapOptions
[src]fn clone(&self) -> MmapOptions
[src]
fn clone(&self) -> MmapOptions
[src]Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
fn clone_from(&mut self, source: &Self)
1.0.0[src]Performs copy-assignment from source
. Read more
impl Debug for MmapOptions
[src]
impl Debug for MmapOptions
[src]impl Default for MmapOptions
[src]
impl Default for MmapOptions
[src]fn default() -> MmapOptions
[src]
fn default() -> MmapOptions
[src]Returns the “default value” for a type. Read more
Auto Trait Implementations
impl RefUnwindSafe for MmapOptions
impl Send for MmapOptions
impl Sync for MmapOptions
impl Unpin for MmapOptions
impl UnwindSafe for MmapOptions
Blanket Implementations
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]pub fn borrow_mut(&mut self) -> &mut T
[src]
pub fn borrow_mut(&mut self) -> &mut T
[src]Mutably borrows from an owned value. Read more
impl<T> ToOwned for T where
T: Clone,
[src]
impl<T> ToOwned for T where
T: Clone,
[src]type Owned = T
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn to_owned(&self) -> T
[src]Creates owned data from borrowed data, usually by cloning. Read more
pub fn clone_into(&self, target: &mut T)
[src]
pub fn clone_into(&self, target: &mut T)
[src]🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more