bookclerk_storage::fs_kind

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

What kind of file system a local path lives on, so the local backend only leans on hard links, inode numbers and atomic renames where the file system keeps their promises.

Network file systems (NFS, SMB/CIFS, AFP, WebDAV, 9p, library file systems) and FUSE mounts break several of them:

  • A retried NFS LINK or RENAME can answer "already exists" or "not found" after the first attempt succeeded, so the answer no longer says whether the operation happened.
  • SMB, AFP and many FUSE file systems have no hard links, or fake them.
  • Inode numbers and status-change times can change after a remount or a cache eviction, so a signature built from them reports changes that never happened.

A library folder can hold another mount below it, so callers classify the directory an operation touches, not the library root.

Item Kind Summary
FsKind enum The kind of file system behind a path.
classify function Classifies the file system that holds path, which must exist.
classify_nearest function Classifies the nearest existing ancestor of path (itself included), so a target that does not exist yet is classified by the directory it will be created in.
device_of function The device id of the file system holding path, where the platform has one. Two paths with different ids are on different file systems, so a rename or hard link between them cannot work.

Enums

FsKind

pub enum FsKind {
    Local,
    Remote,
    Userspace,
    Unknown,
}

The kind of file system behind a path.

Variants

  • Local: A disk the operating system manages directly (ext4, XFS, Btrfs, ZFS, APFS, NTFS, FAT and the like).
  • Remote: A network or library file system, or a Windows network drive.
  • Userspace: A FUSE (or macFUSE) mount: its guarantees depend on the program behind it, so it is treated like a remote file system.
  • Unknown: The kind could not be determined; treated like a remote file system.

FsKind::is_local

pub fn is_local(self) -> bool

True when hard links, rename and inode identity behave as on a local disk, so a hard link can publish a file atomically and an inode number can be part of a change signature.

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

classify

pub fn classify(path: &Path) -> FsKind

Classifies the file system that holds path, which must exist.

Returns FsKind::Unknown when the platform gives no answer.

classify_nearest

pub fn classify_nearest(path: &Path) -> FsKind

Classifies the nearest existing ancestor of path (itself included), so a target that does not exist yet is classified by the directory it will be created in.

device_of

pub fn device_of(path: &Path) -> Option<u64>

The device id of the file system holding path, where the platform has one. Two paths with different ids are on different file systems, so a rename or hard link between them cannot work.

Generated from crates/bookclerk-storage at main · View as Markdown