mmarinus/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! The `mmarinus` crate wraps the underlying system `mmap()` call in safe semantics.
4//!
5//! For example:
6//!
7//! ```rust
8//! use mmarinus::{Map, perms};
9//!
10//! let mut zero = std::fs::File::open("/dev/zero").unwrap();
11//!
12//! let map = Map::bytes(32)
13//!     .near(128 * 1024 * 1024)
14//!     .from(&mut zero, 0)
15//!     .with(perms::Read)
16//!     .unwrap();
17//!
18//! assert_eq!(&*map, &[0; 32]);
19//! ```
20//!
21//! You can also remap an existing mapping:
22//!
23//! ```rust
24//! use mmarinus::{Map, perms};
25//!
26//! let mut zero = std::fs::File::open("/dev/zero").unwrap();
27//!
28//! let mut map = Map::bytes(32)
29//!     .anywhere()
30//!     .from(&mut zero, 0)
31//!     .with(perms::Read)
32//!     .unwrap();
33//!
34//! assert_eq!(&*map, &[0; 32]);
35//!
36//! let mut map = map.remap()
37//!     .from(&mut zero, 0)
38//!     .with(perms::ReadWrite)
39//!     .unwrap();
40//!
41//! assert_eq!(&*map, &[0; 32]);
42//! for i in map.iter_mut() {
43//!     *i = 255;
44//! }
45//! assert_eq!(&*map, &[255; 32]);
46//! ```
47//!
48//! Alternatively, you can just change the permissions:
49//!
50//! ```rust
51//! use mmarinus::{Map, perms};
52//!
53//! let mut zero = std::fs::File::open("/dev/zero").unwrap();
54//!
55//! let mut map = Map::bytes(32)
56//!     .at(128 * 1024 * 1024)
57//!     .from(&mut zero, 0)
58//!     .with(perms::Read)
59//!     .unwrap();
60//!
61//! assert_eq!(&*map, &[0; 32]);
62//!
63//! let mut map = map.reprotect(perms::ReadWrite).unwrap();
64//!
65//! assert_eq!(&*map, &[0; 32]);
66//! for i in map.iter_mut() {
67//!     *i = 255;
68//! }
69//! assert_eq!(&*map, &[255; 32]);
70//! ```
71//!
72//! Mapping a whole file into memory is easy:
73//!
74//! ```rust
75//! use mmarinus::{Map, Private, perms};
76//!
77//! let map = Map::load("/etc/os-release", Private, perms::Read).unwrap();
78//! ```
79
80#![forbid(clippy::expect_used, clippy::panic)]
81#![warn(
82    rust_2018_idioms,
83    unused_lifetimes,
84    unused_qualifications,
85    clippy::all,
86    missing_docs
87)]
88
89mod builder;
90mod error;
91mod map;
92
93pub use error::Error;
94pub use map::{Map, Private, Shared};
95pub mod perms;
mmarinus/lib.rs

mmarinus/
lib.rs
