Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation

Every crate in the workspace builds on Rust 1.88 or newer.

The library

ferrosys is a Rust library. Add it to a project with:

cargo add ferrosys

or by editing Cargo.toml:

[dependencies]
ferrosys = "0.8"

The build is pure Rust, and features shape it: the first five are the filesystem families. The default build carries the first four and the three decoders they read. It reads what a Linux kernel mounts, a compressed btrfs root included. It depends on thiserror, miniz_oxide, and ruzstd. APFS is named with the decoders a Mac’s compressed files use:

[dependencies]
ferrosys = { version = "0.8", features = ["apfs", "lzvn", "lzfse", "lzbitmap"] }

A build that names its own features takes only the families it names. A consumer that wants an ext image alone compiles no FAT code:

FeatureDefaultWhat it addsWhat it depends on
extonThe ext2/ext3/ext4 family, under the ext module: the formatter, the reader, the feature model, and the on-disk structures—
fatonThe FAT12/FAT16/FAT32 family, under the fat module: the formatter, the reader, the geometry planner, the on-disk structures, and the classifier that recognizes a FAT volume—
exfatonThe exFAT family, under the exfat module: the formatter, the reader, the planner, the on-disk structures, and the classifier—
btrfsonThe btrfs family, under the btrfs module: the reader over its two layers, the formatter, the B-tree engine, the chunk map, and the on-disk structures—
apfsoffThe APFS family, under the apfs module: the container and volume reader, snapshots, the scan, the geometry planner, the formatter, the on-disk structures, and the classifierferrosys-ucd
zlibonReading a btrfs extent, or an APFS file’s chunks, stored as DEFLATEminiz_oxide
lzoonReading a file whose extents are stored as LZO1X—
zstdonReading a file whose extents are stored as Zstandardruzstd
lzvnoffReading an APFS file whose content is compressed with LZVNferrosys-lzfse
lzfseoffReading an APFS file whose content is compressed with LZFSE. It turns lzvn on, since an LZFSE stream carries LZVN blocks among its ownferrosys-lzfse
lzbitmapoffReading an APFS file whose content is compressed with LZBITMAP—
taroffArchiveSource and ArchiveSink: a filesystem built from a tar stream, and one written back out as one, with PAX times, SCHILY.xattr.* attributes, and SCHILY.acl.* recordstar
diroffDirectorySource and DirectorySink: a filesystem built from a directory tree on this machine, and one written back out as a tree, with modes, ownership, times, hard links, special files, and extended attributes. Built on Linux, whose metadata and extended attributes both ends read and writerustix
serdeoffSerialize on the findings taxonomy, each family’s scan report and planned layout, the fidelity report, Usage, and the ext feature model, for embedding them in a document of your ownserde

Granularity is per family rather than per format. ext is ext2, ext3, and ext4 together, and fat is FAT12, FAT16, and FAT32 together. Each set is one lineage that shares its on-disk structures.

Every crate of this project is under MIT OR Apache-2.0 but two, and each of those is reached through a feature that names it. ferrosys-ucd, which apfs depends on, holds the Unicode Character Database tables APFS names are compared with, under the Unicode License v3. ferrosys-lzfse, which lzvn and lzfse depend on, holds the LZVN and LZFSE decoders, derived from Apple’s lzfse project and under its BSD-3-Clause license. The default build compiles this project’s code under MIT OR Apache-2.0 alone.

The six decoders are named for the algorithm, not for a family. An encoding is a property of a run of bytes, not of the format around it. Of the families here, btrfs and APFS are the ones that store runs that way. A build that names its own features and wants to read them names a decoder beside it: --features btrfs,zstd, or --features apfs,zlib,lzfse,lzbitmap.

Each decoder decides what a file does when it is read. A build lacking the decoder for the algorithm a file was stored with declines that file by name. A build lacking a decoder for an algorithm the filesystem advertises in its feature word declines the filesystem itself.

Verification is a separate question and needs none of them. The checksums a filesystem records cover the bytes it stored, so ferrosys checks them whether or not those bytes can be expanded.

default-features = false is a real build, not a smaller version of the same one. It leaves the family-agnostic substrate the crate root carries. That is the crc32c primitive, the source and extraction vocabulary, and detect, which says which filesystem an image holds. It leaves no family code at all, so detect then recognizes nothing, and it depends on thiserror alone. It is the build a consumer starts from when it wants some families and not the others:

[dependencies]
ferrosys = { version = "0.8", default-features = false, features = ["ext", "tar"] }

None of tar, dir, or serde names a family. A source feeds whichever family the writer makes, and a sink takes whichever one the reader opened. So --no-default-features --features fat,dir builds a FAT volume from a directory tree on this machine and extracts one back, with no ext code compiled. An application that wants the default families and both sources names the two beside them:

[dependencies]
ferrosys = { version = "0.8", features = ["tar", "dir"] }

Cargo unifies features across a dependency graph. Naming a subset is therefore a property of a leaf application, not of a library deep in someone’s tree. Anything in the build that pulls this crate with a family turns that family on for everyone in it. That includes the answers detect then gives. A library depending on this crate therefore turns the default off and names what it reads. Otherwise it turns the four default families on for every build it joins.

The API reference documents the public surface.

The command line

The ferrosys binary writes, inspects, and reads back filesystems from a shell prompt. Install it from the registry:

cargo install ferrosys-cli

or from a checkout of the workspace:

cargo install --path crates/ferrosys-cli

It writes to a regular file, takes its identifiers and timestamps as inputs, and exits as e2fsck does. The command-line chapter covers it.