fs2

fs2 provides cross-platform file locking, allocation, duplication, and filesystem statistics. Version 1.0 preserves the public fs2 0.4 API while retaining the correctness and safety fixes developed in this maintained fork. It uses Rust 2024 and requires Rust 1.88 or newer.

The original implementation is from danburkert/fs2-rs. This maintained fork lives at github.com/arthurianresolve/fs2-rs.

Features

• File descriptor duplication.
• Shared and exclusive file locks.
• File preallocation and allocated-size queries.
• Filesystem snapshots and scalar space queries.
• Prepared FsStatsQuery values for repeated fresh snapshots.

On Unix and Windows, FileExt::duplicate retains the original crate's inheritable duplicate semantics. Use File::try_clone when the duplicate must not be inherited by a child process.

Compatibility

The v0.4 FileExt methods and their behavior remain available. Rust 1.97 and newer also provide inherent locking methods on std::fs::File; use fully qualified calls when the fs2 implementation must be selected explicitly:

use fs2::FileExt;
use std::fs::File;
use std::io;

fn locked(file: &File) -> io::Result<()> {
    FileExt::lock_exclusive(file)?;
    FileExt::unlock(file)
}

The fs2_lock_shared, fs2_lock_exclusive, fs2_try_lock_shared, fs2_try_lock_exclusive, and fs2_unlock forwarding methods are retained for collision-safe migration code.

Platforms

fs2 supports the Unix and Windows targets implemented by the platform adapters in this repository. Unix support uses libc; Windows support uses windows-sys.

On Windows, filesystem snapshots report physical total capacity when the modern disk-space provider is available. On systems that require the legacy fallback, the reported total may be limited by the calling user's disk quota.

The CI matrix continuously tests the native x86_64 targets on Linux, macOS, and Windows with Rust 1.88 and stable. The historical 32-bit and GNU Windows targets are not currently covered by the native test matrix. The armv7-unknown-linux-uclibceabihf target is compile-checked separately with nightly build-std; runtime tests require a target-specific emulator and uClibc sysroot.

The target evidence and allocation capability claims are recorded in the repository-only support-matrix.json registry. CI validates the matrix and generates its native and cross-target job matrices from the registry, then runs native runtime tests and compile-checks the listed cross targets. Compile-only evidence does not imply runtime support.

Benchmarking

Stable Criterion benchmarks are provided for the public APIs in the separate fs2-benchmarks workspace member. From a repository checkout, run them with cargo bench --manifest-path benchmarks/Cargo.toml. When benchmarking files, account for the filesystem backing the temporary directory; /tmp is often a tmpfs mount.

statvfs is the snapshot-first interface: it acquires and validates one consistent set of filesystem counters. When several counters are needed, prefer one statvfs snapshot and read its accessors rather than calling the individual convenience functions, which each acquire a new snapshot. When an application needs fresh snapshots repeatedly for the same filesystem, construct FsStatsQuery once and call snapshot; it reuses platform path preparation without caching counter values. The stats_snapshot and prepared_stats benchmark groups measure both usage patterns. On Windows, the windows_root_stats group also measures exact drive-root preparation and scalar queries.

Repository operations are implemented by the unpublished Rust fs2-dev tool:

cargo xtask matrix
cargo xtask compatibility
cargo xtask policy
cargo xtask bench refs --help
cargo xtask bench crates --help
cargo xtask bench lock --help
cargo xtask bench stats --help

The compatibility command compiles one frozen v0.4 consumer against exact fs2 0.4.3 and the current checkout across Rust editions 2015 through 2024. The benchmark commands stage subjects independently, retain typed process outcomes and artifacts, and apply the versioned policy in benchmarks/measurement-policy.json.

Every benchmark subject receives one explicit unmeasured priming invocation in each fresh process before Criterion warm-up. A separate single-execution process records cold-start duration, outcome, and errors. Neither source is included in runtime estimates, medians, ratios, confidence bounds, or Criterion samples. Stable comparisons use exact, distribution-free one-sided 95% median bounds and reject any affected workload whose upper candidate-to-baseline ratio exceeds 1.02. Windows filesystem-stat comparisons additionally use same-process alternating calls and an A/A control to detect host and fixture-order drift.

Development validation

The supported local entry points are:

cargo +1.88.0 fmt --all -- --check
cargo +1.88.0 test --workspace --locked
cargo +1.88.0 clippy --workspace --all-targets --locked -- -D warnings
cargo +1.97.1 test --workspace --locked
cargo xtask matrix
cargo xtask compatibility
cargo xtask policy

Release CI also builds documentation and benchmarks, checks future incompatibilities, audits locked dependencies, validates package contents, and builds the extracted package. Repository tooling, policies, compatibility fixtures, and benchmarks are excluded from the published crate.

License

fs2 is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Copyright (c) 2015 Dan Burkert.