mmap-guard

Safe, guarded memory-mapped file I/O for Rust. Wraps memmap2::Mmap::map() behind a safe API so downstream crates can use #![forbid(unsafe_code)] while still benefiting from zero-copy file access.

Why mmap-guard?

Projects that enforce #![forbid(unsafe_code)] cannot call memmap2::Mmap::map() directly because it is unsafe. The alternative — std::fs::read() — copies the entire file into heap memory, which is impractical for disk images and multi-gigabyte binaries.

mmap-guard bridges this gap by isolating the unsafe boundary in a single, focused crate. By centralizing it here, we can concentrate testing, fuzzing, and hardening efforts on that one point — so every consumer benefits from those protections without reasoning about mmap safety themselves.

Features

Safe mmap construction — wraps memmap2::Mmap::map() with pre-flight checks (empty file detection, permission errors)
Platform quirk mitigation — documents and (where possible) mitigates SIGBUS/access violations from file truncation
Unified read API — returns &[u8] whether backed by mmap or a heap buffer (for stdin/non-seekable inputs)
Zero unsafe for consumers — exactly one unsafe block, fully documented with a // SAFETY: comment
Minimal dependencies — only memmap2 at runtime

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
mmap-guard = "0.1"

Usage

use mmap_guard::map_file;

// Memory-map a file — returns FileData that derefs to &[u8]
let data = map_file("large-file.bin")?;
assert!(!data.is_empty());
// Use it like any byte slice
println!("first byte: {:#04x}", data[0]);

For CLI tools that accept both file paths and stdin:

use mmap_guard::{load, load_stdin};
use std::path::Path;

let path = Path::new("input.txt");
let data = if path == Path::new("-") {
    load_stdin()?
} else {
    load(path)?
};

Architecture

graph TD
    load["load()"] --> map_file
    load_stdin["load_stdin()"] --> FileData
    map_file["map_file()"] --> unsafe["unsafe { Mmap::map() }"]
    unsafe --> FileData["FileData<br/>Deref&lt;Target=[u8]&gt;"]
    FileData --- Mapped["Mapped(Mmap)"]
    FileData --- Loaded["Loaded(Vec&lt;u8&gt;)"]

Module	Purpose
`src/lib.rs`	Crate-level docs, re-exports public API
`src/map.rs`	`map_file()` with pre-flight stat check; the single `unsafe` block
`src/load.rs`	`load()` delegates to `map_file()`; `load_stdin()` reads to heap
`src/file_data.rs`	`FileData` enum (`Mapped` / `Loaded`), `Deref`, `AsRef`

What It Does NOT Do

Provide mutable/writable mappings
Manage file locking or concurrency
Abstract over async I/O
Implement its own mmap syscalls (delegates entirely to memmap2)

Safety

This crate contains exactly one unsafe block — the call to memmap2::Mmap::map(). The safety contract is maintained through:

File opened read-only (File::open())
File descriptor kept alive through ownership in FileData
No mutable aliasing (read-only mappings only)
#![deny(clippy::undocumented_unsafe_blocks)] enforced

See the safety documentation for the full contract and known limitations (SIGBUS from concurrent file truncation).

Security

Strict linting — pedantic/nursery/cargo clippy groups, unwrap_used denied, panic denied
Dependency auditing — cargo audit and cargo deny in CI
Coverage threshold — 80%+ project coverage enforced
Supply chain — OpenSSF Scorecard monitoring

Documentation

Developer Guide — mdBook documentation
API Reference — docs.rs
GitHub Issues

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Licensed under the Apache License 2.0 — see LICENSE for details.

Acknowledgments

memmap2 for the underlying memory-mapping implementation
The Rust community for excellent tooling and ecosystem

mmap-guard 0.1.0