fs2

fs2 is a small Rust crate that fills gaps left by the standard library’s std::fs around file-level concurrency and filesystem introspection: advisory file locking (shared and exclusive, blocking and non-blocking), file descriptor/handle duplication, file preallocation, and filesystem space-usage queries. It normalizes these operations across Unix (via libc flock/fcntl) and Windows (via WinAPI file APIs) behind one consistent API.

Because Rust’s standard library still doesn’t expose portable file locking or space-usage APIs, fs2 has become a common low-level dependency for databases, log rotators, and other tools that need to coordinate exclusive access to a file across processes or check available disk space before writing.

What You Get

• A FileExt trait adding lock_shared, lock_exclusive, try_lock_shared, try_lock_exclusive, and unlock methods directly onto std::fs::File
• File descriptor/handle duplication (duplicate) so callers can hold two independent handles to the same open file
• File preallocation (allocated_size, allocate) for reserving disk space ahead of writes
• Filesystem space-usage queries (statvfs-equivalent on Unix, GetDiskFreeSpaceEx-equivalent on Windows) via a FsStats type

Common Use Cases

• Coordinating exclusive or shared access to a shared file (e.g. a database file, lock file, or log file) across multiple processes
• Checking available disk space before writing large files, to fail gracefully instead of running out of space mid-write
• Preallocating disk space for a file that will be written to incrementally, to reduce fragmentation
• Duplicating a file handle to hand off independent read/write cursors to different parts of an application

Under The Hood

Architecture — The crate is intentionally small: src/lib.rs (458 lines) defines the public FileExt trait and FsStats type, with all OS-specific logic isolated into src/unix.rs (251 lines, libc-based flock/fcntl and statvfs calls) and src/windows.rs (279 lines, WinAPI LockFileEx/GetDiskFreeSpaceEx calls), selected at compile time via cfg(unix)/cfg(windows) target configuration in Cargo.toml. This trait-extension pattern lets consumers call .lock_exclusive() directly on a std::fs::File without any wrapper type.

Tech Stack — Pure Rust with platform-conditional dependencies: libc 0.2.30+ on Unix targets, winapi 0.3 (with handleapi/processthreadsapi/fileapi/winbase features) on Windows targets. No async runtime or heavier dependencies are pulled in — this is a thin FFI-adjacent layer over each OS’s native file APIs.

Code Quality — The crate is small enough that its two platform backends (Unix, Windows) can each be read end-to-end in a few minutes; dev-dependencies include tempdir for test fixtures. The project has had no releases since 2018 and low recent commit activity, which is consistent with a stable, feature-complete utility crate rather than a sign of abandonment — the underlying OS file-locking APIs it wraps haven’t changed.

API Design — By extending std::fs::File via a trait (FileExt) rather than introducing a new wrapper type, fs2 keeps the learning curve minimal: existing File handles gain lock/duplicate/allocate methods with no migration needed. This is the same ergonomic pattern Rust’s own std::os::unix::fs::FileExt/std::os::windows::fs::FileExt use, making fs2 feel like a natural stdlib extension rather than a separate abstraction to learn.