ferrosys 0.8.0

Pure-Rust filesystem formatter and reader: ext4, ext3, ext2, FAT32, FAT16, FAT12, exFAT, btrfs, and APFS — rootless, in userspace, byte-reproducible
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
//! `ferrosys` — pure-Rust, userspace filesystem tooling.
//!
//! The crate creates and reads filesystem images entirely in userspace, over ordinary byte
//! streams, in self-contained, safe Rust. On-disk types serialize through explicit
//! little-endian byte accessors, so the byte layout is spelled out at every field.
//!
//! # Structure
//!
//! The crate root holds what is true of a filesystem whatever family it is, and each family
//! lives in a module of its own behind a feature of its own.
//!
//! **Finding one, and opening it.**
//!
//! - [`detect`](fn@detect) reads an image and reports the [`Filesystem`] family it holds, and
//!   [`detect_with`] does the same at an offset within the source, for a partition or a
//!   region a carver located; [`DetectError`] tells an unreadable source from an
//!   unrecognized one.
//! - [`OpenOptions`], [`ReadPolicy`], and [`Limits`] say where to look, how strictly, and
//!   within what bounds a read may allocate.
// The bullet belongs to the builds that have the item: with no family compiled in there is
// nothing an image could be opened as, so `open` and `FsReader` are not there to link.
#![cfg_attr(
    any(
        feature = "ext",
        feature = "fat",
        feature = "exfat",
        feature = "btrfs",
        feature = "apfs"
    ),
    doc = " - [`open`](fn@open) detects and hands back the matching family's reader, as an \
[`FsReader`] — an enum of concrete readers rather than a common interface, so a caller that \
has matched its way to one has that family's whole surface."
)]
//!
//! **Describing a tree, and draining one.** A directory tree is not any family's concept, so
//! the vocabulary for one is here and every family consumes it unchanged.
//!
//! - [`Source`], [`SourceEntry`], [`EntryKind`], [`Metadata`], [`FileContent`], [`Xattr`],
//!   and [`Timestamp`] describe what to write; [`TreeBuilder`] and [`LayeredSource`] build
//!   one programmatically.
//! - [`FsTree`] is the other direction, and the one behavioural trait the families share:
//!   walk the names, stat one, stream a file's bytes, resolve a link, find a path, list a
//!   directory, and report the room. It is what lets a sink drain any family without knowing
//!   which.
//!
//! **Saying what was lost, and what was found.**
//!
//! - [`FidelityReport`] names every property a format could not hold and every value a read
//!   had to invent, and [`Synthesis`] is what a read invents them from — with conservative
//!   defaults, because a tree extracted from a format with no permission bits must not land
//!   world-writable because nothing was named. A build that would lose a property fails
//!   until the caller names it in an [`AcceptedLoss`], so nothing is dropped unacknowledged.
//! - [`Finding`] is what a scan reports, carrying a [`Severity`], a byte offset, the
//!   [`Family`] that found it, and that family's own words for the rest. Each family keeps
//!   its own typed taxonomy and projects into this, so there is one document shape and one
//!   severity scale however many families a build carries.
//! - [`printable`](fn@printable) renders a name that came off an image as text a terminal
//!   will not act on, and [`push_json_string`] does the same into a JSON document. Every
//!   message and every finding this crate produces has already been through them; they are
//!   public for a caller whose own output names the same untrusted bytes.
//! - [`crc32c`](fn@crc32c) is the reflected CRC-32C primitive filesystem metadata checksums
//!   are built from.
#![cfg_attr(
    feature = "ext",
    doc = "\n The [`ext`] module implements the ext2/ext3/ext4 family — the \
[`format`](ext::format) writer, the [`Reader`](ext::Reader) opened over any `Read + Seek` \
source, and the byte-exact on-disk structures. Its images are \
byte-reproducible: the UUID, hash seed, and timestamps are inputs, never read from the \
clock or a random source. It re-exports the root vocabulary above, so a caller formatting \
an ext image names one namespace rather than two."
)]
#![cfg_attr(
    feature = "fat",
    doc = "\n The [`fat`] module implements the FAT12/FAT16/FAT32 family — the \
[`format`](fat::format) writer, the [`Reader`](fat::Reader), the \
[`plan_layout`](fat::plan_layout) geometry planner, and the byte-exact on-disk structures \
under [`fat::ondisk`]. Which of the three a volume is follows from its cluster count and \
from nothing else, so the type is derived rather than chosen, and the arithmetic that \
derives it is the format's real contract. Its images are byte-reproducible: the volume \
serial number and the times a directory entry carries are inputs, and the date conversion \
is UTC, so nothing about the machine that wrote an image reaches it. The reader reads any \
conformant volume with one or two allocation tables, whatever wrote it, and takes one input \
no other family has — \
[`ShortNameCharset`](fat::ShortNameCharset), since nothing in a FAT volume records the code \
page its short names are written in and this crate does not guess one."
)]
#![cfg_attr(
    feature = "exfat",
    doc = "\n The [`exfat`] module implements the exFAT family — the \
[`format`](exfat::format) writer, the [`Reader`](exfat::Reader), the \
[`plan_layout`](exfat::plan_layout) geometry planner, and the byte-exact on-disk structures \
under [`exfat::ondisk`]. It shares a name with FAT and \
no bytes: a different boot region, a different directory entry format, a different name \
encoding, and an allocation bitmap FAT has no equivalent of. Three of its structures carry a \
checksum and a fourth carries a hash, and every one is recomputed rather than copied. Its \
images are byte-reproducible, and cost one input to be so — the volume serial number, since \
an empty exFAT volume records no time anywhere."
)]
#![cfg_attr(
    feature = "btrfs",
    doc = "\n The [`btrfs`] module implements the btrfs family, over the two layers the format \
has. A [`Volume`](btrfs::Volume) opens one over any `Read + Seek` source and gives the lower \
one: the superblock and every mirror of it the device holds, the chunk map that turns a \
logical address into a place on the device, and a [`Tree`](btrfs::Tree) over any of the \
filesystem's B-trees — searched by the key tuple, iterated in key order, with every block's \
checksum verified as it is read. A [`Reader`](btrfs::Reader) is the filesystem view built on \
that, and [`FormatPlan`](btrfs::FormatPlan) writes one, subvolumes included. Reading a file \
whose bytes are compressed takes the decoder for its algorithm; verifying one takes none, the \
checksums covering the bytes on the volume. The byte-exact on-disk structures are under \
[`btrfs::ondisk`]."
)]
#![cfg_attr(
    feature = "apfs",
    doc = "\n The [`apfs`] module reads the APFS family, over the two layers the format has. A \
[`Container`](apfs::Container) opens one over any `Read + Seek` source at its newest whole \
checkpoint and lists the volumes it holds, and a [`Reader`](apfs::Reader) is one of those \
volumes read as files, or one of its snapshots. Every object's checksum is verified and every \
object is held to the reference that reached it; a compressed file reads through its compression \
header, its content after the header or in its resource fork. [`format`](apfs::format) writes a \
container as `newfs_apfs` writes one into a file, its first volume populated from a source. The \
byte-exact on-disk structures are under [`apfs::ondisk`]."
)]
//!
//! # Features
//!
//! A build takes the filesystem families it names. The default build carries four — `ext`,
//! `fat`, `exfat` and `btrfs` — and the three decoders they read, so it reads what a Linux
//! kernel mounts, a compressed btrfs included. The fifth family, `apfs`, is named beside the
//! decoders a Mac's compressed files use, as `features = ["apfs", "lzvn", "lzfse", "lzbitmap"]`.
//! `apfs`, `lzvn` and `lzfse` depend on this project's two crates under licenses of their own,
//! the Unicode License v3 and BSD-3-Clause, so the default build compiles this project's code
//! under MIT OR Apache-2.0 alone. A build that turns off
//! every family compiles the root substrate and no family code at all, and
//! [`detect`](fn@detect) then recognizes nothing. Granularity is per *family* rather than per
//! format — `ext` is ext2, ext3, and ext4 together, and `fat` is FAT12, FAT16, and FAT32
//! together, since each set is one lineage sharing its on-disk structures.
//!
//! Cargo unifies features across a dependency graph, so selecting a subset is a property of
//! a leaf application rather than of a library deep in someone's tree: anything else in the
//! build that pulls this crate with a family turns that family on for everyone in it —
//! including the answers [`detect`](fn@detect) then gives.
//!
//! Each feature stands alone but `lzfse`, which turns `lzvn` on, since an LZFSE stream carries
//! LZVN blocks among its own. The two ends of a tree are the root's vocabulary, so a source
//! feeds whichever family is being written and a sink drains whichever one was opened, and a
//! decoder undoes an encoding whichever family stored a run of bytes in it. The seven the
//! default build carries:
//!
//! - **`ext`** adds the ext2/ext3/ext4 family. It has no dependencies of its own.
//! - **`fat`** adds the FAT12/FAT16/FAT32 family. It has no dependencies of its own.
//! - **`exfat`** adds the exFAT family, which shares a name with the one above and none of
//!   its structures. It has no dependencies of its own.
//! - **`btrfs`** adds the btrfs family, over a format built out of B-trees and a logical
//!   address space. It has no dependencies of its own.
//! - **`zlib`**, **`lzo`** and **`zstd`** each add a decoder, so that a file whose extents
//!   are stored in that encoding reads as the file rather than as a refusal naming the
//!   algorithm. btrfs stores extents in all three, and APFS keeps a compressed file's content
//!   in `zlib` as well. A decoder reaches bytes only through a family that stores some, so a
//!   build naming its features names one beside such a family, as `--features btrfs,zstd`;
//!   alone it compiles its dependency and decodes nothing, since no reachable read stores runs
//!   that way. `lzo` takes no
//!   dependency, its decoder being in this crate; the other two depend on `miniz_oxide`
//!   and `ruzstd`. None of them is needed to *verify* a filesystem: the checksums it
//!   records cover the bytes it stored, so a compressed extent is checked without being
//!   expanded.
//!
//! The four named beside APFS, two of which depend on a crate under a license of its own:
//!
//! - **`apfs`** adds the APFS family: a container of volumes under a checkpoint, each volume a
//!   tree of records found through an object map, read, and written from a source tree. It
//!   depends on `ferrosys-ucd`, the Unicode Character Database tables a volume's names are
//!   compared with, which are under the Unicode License v3.
//! - **`lzvn`**, **`lzfse`** and **`lzbitmap`** add the decoders an APFS compressed file's
//!   chunks are stored with beside `zlib`, so that such a file reads as its content rather than
//!   as a refusal naming its compression type. `lzvn` and `lzfse` depend on `ferrosys-lzfse`,
//!   whose decoders are derived from Apple's lzfse project and are under its BSD-3-Clause
//!   license, and `lzfse` turns `lzvn` on, since an LZFSE stream carries LZVN blocks among its
//!   own. `lzbitmap` takes no dependency, its decoder being in this crate.
//!
//! Three more name no family and are off by default, so the default build's dependencies are
//! `thiserror` and the two decoders':
//! - **`tar`** adds the tar/PAX archive source and sink: a filesystem built from an
//!   archive, and one written back out as one. It depends on `tar`.
//! - **`dir`** adds the host-directory source and sink: a filesystem built by walking a
//!   tree on this machine, and one written back out as a tree, with modes, ownership,
//!   times, hard links, special files, and extended attributes. It depends on `rustix`
//!   for the directory, node, ownership and extended-attribute calls the standard library
//!   has no equivalent of, and is present on Linux.
//! - **`serde`** adds `Serialize` to the findings taxonomy, each family's scan report and
//!   planned geometry, the fidelity report, `Usage`, and the ext feature model, for embedding
//!   them in a document of your own. It depends on `serde`.
// The crate is safe by construction: on-disk types serialize through explicit
// little-endian byte accessors, never transmutes or `zerocopy`.
#![forbid(unsafe_code)]
#![warn(missing_docs)]

/// The crate's README, compiled as a doctest so the example on its front page is the
/// example this crate's API actually accepts. The item exists only while rustdoc is
/// collecting doctests, so it is neither part of the crate nor part of its documentation.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct Readme;

// ── Generic substrate: the crate root ──
//
// Present regardless of which family backends are enabled. The root exposes only what a
// detector or a scan produces independent of the family that answers it.

// The reflected CRC-32C primitive. The module is pure and has no family dependencies.
mod crc32c;
pub use crc32c::crc32c;

// Undoing the encodings a filesystem stores a run of bytes in fewer of them. Here beside
// `crc32c` and for the same reason: an encoding is a property of a run of bytes rather than
// of the format around it, and the same algorithms appear in more than one filesystem. How a
// format frames them stays with the format. Compiled where a family that stores runs this way
// is; the decoders inside it are each a feature of their own, so a build with that family and
// none of them still names the encoding it is declining.
#[cfg(any(feature = "btrfs", feature = "apfs"))]
mod compress;

// The digests a filesystem may checksum with besides crc32c, here beside it and for the same
// reason: a digest is a property of a run of bytes. Compiled where btrfs, the family that
// checksums with them, is.
#[cfg(feature = "btrfs")]
mod digest;

// The little-endian byte accessors every family's on-disk layer serializes through. Two
// families compute them identically with nothing interpreted, which is what makes them a
// shared primitive rather than a shared seam. Not compiled behind a family: the POSIX ACL
// boundary form is a fixed little-endian record that the family-agnostic substrate parses,
// so a build carrying no family still reads fields out of a buffer.
mod bytes;

// The blocks a reader returns to, held so the source is asked for each once. Which blocks
// are worth holding is the family's; how many are held and which goes first is the same
// answer for every reader that holds any.
#[cfg(any(feature = "ext", feature = "btrfs", feature = "apfs"))]
mod cache;

// The byte boundary, in both directions. Deciding what a byte is, and finding the structure
// that holds it, belong to the family; seeking to an offset and moving exactly that many
// bytes is the same operation for every one of them, and so is the checked arithmetic that
// names the offset. Both are here and the layout logic stays with the family. This also
// holds what an i/o failure records and the conversion every error type carrying one is
// written by, which is why the module is not compiled behind a family: `DetectError` carries
// one in every build.
mod io;

// Rendering bytes that came off an image, an archive, or a host tree as text. Every name
// every family reads is a byte string that may hold whatever a terminal acts on, and a
// message or a finding that interpolates one raw hands those bytes on — so the escaping
// happens where the name enters the text, which is the last point anything can tell it apart
// from the words around it. Both renderings are public because a caller building its own
// output faces the same problem with the same names, and a second implementation of these
// rules is a second place for them to drift.
mod escape;
pub use escape::{hex, printable, push_json_string};

// Building a JSON document, as against escaping the strings that go into one. Comma
// placement and value formatting are the same rules whatever document is being written, so
// they live here and every document this crate or a consumer emits is built through them —
// the same move `escape` is, one level up from the characters.
pub mod json;

// The depth-first walk every family's reader is driven by: one frontier, one cycle check,
// one set of bounds, with each family supplying what sits on the frontier and how a name's
// children are read. Compiled where a family is, since with none there is no tree to walk.
#[cfg(any(
    feature = "ext",
    feature = "fat",
    feature = "exfat",
    feature = "btrfs",
    feature = "apfs"
))]
mod walk;

// The path resolution every family's reader answers a lookup with: one component loop, one
// ascent on `..`, one hop budget for symbolic links, with each family supplying only how a
// name is found in a directory. Compiled where a family is, for the same reason the walk is.
#[cfg(any(
    feature = "ext",
    feature = "fat",
    feature = "exfat",
    feature = "btrfs",
    feature = "apfs"
))]
mod resolve;

// One shape for a newtype over a field of on-disk flag bits: the set operations every one of
// them needs, so no two of them have different ones. Compiled where a family is, since with
// none there is no on-disk flag word.
#[cfg(any(feature = "ext", feature = "fat", feature = "exfat", feature = "btrfs"))]
mod flags;

// One table per named choice, generating the word a variant is written as, the list of
// them, and the variant a word means. Every set of choices a caller names goes through it,
// so a vocabulary cannot be spelled twice and drift. `NamedChoice` is public because the
// same three questions are what a consumer's own argument parser asks, and asking them
// generically is what keeps its list of choices from being a second copy of this one.
mod naming;
pub use naming::NamedChoice;

// Image detection and the family selector it returns. `Filesystem` and `DetectError` are
// always present; `detect` dispatches across whichever families are compiled in.
mod detect;
pub use detect::{DetectError, DetectOptions, Filesystem, detect, detect_with};

// What a path is made of, and which of its components a directory can hold. Both questions
// are asked by every family and on both sides of each of them — a source keying entries, a
// model placing them, a reader resolving one, a sink creating one — so both are answered
// here. A second answer that drifted would not fail; it would key two entries apart that the
// model considers one path, or refuse a name where it is read and accept it where it is
// written.
mod path;

// A wall-clock instant, and one extended attribute. Both are boundary vocabulary rather
// than storage: how an instant splits across fields and how an attribute's name compresses
// are the family's business, and each family's on-disk layer carries its own conversion.
//
// The DOS date is where that rule has an exception, and it is here because FAT and exFAT
// carry one encoding rather than two — the same packed words, epoch, and granularity,
// inherited from the same ancestor. Where each format puts those words in an entry stays in
// that family's own layer, so this is compiled only where a family that stores it is.
mod time;
#[cfg(any(feature = "fat", feature = "exfat"))]
pub use time::DosTimestamp;
pub use time::{Civil, Timestamp};
mod xattr;
pub use xattr::Xattr;

// What populates a filesystem. A directory tree is not an ext concept, so the vocabulary
// that describes one lives here and every family consumes it — what a family can
// *represent* of an entry is that family's business, not a reason to give each family a
// source vocabulary of its own.
mod source;
pub use source::{
    CompressedFile, Darwin, EntryKind, FileContent, FileRange, LayeredSource, Metadata,
    RemovalError, Source, SourceEntry, TreeBuilder,
};

// What a scan found, and what renders it. A family keeps its own typed taxonomy and
// projects into `Finding`, so there is one document shape and one severity scale however
// many families a build carries.
mod finding;
pub use finding::{
    Coordinate, Deviation, FINDINGS_SCHEMA_VERSION, Family, Finding, FindingReport, ScanReport,
    Severity,
};

// Where a filesystem begins, how strictly it is read, and what one read may allocate — the
// same three settings whatever family answers them.
mod policy;
#[cfg(any(
    feature = "ext",
    feature = "fat",
    feature = "exfat",
    feature = "btrfs",
    feature = "apfs"
))]
pub use policy::MAX_SYMLINK_HOPS;
pub use policy::{Limits, OpenOptions, ReadPolicy};

// Opening an image without naming its family. Compiled only where a family is: `FsReader`
// is an enum of concrete readers, one per family, so a build carrying none has nothing for
// it to hold.
#[cfg(any(
    feature = "ext",
    feature = "fat",
    feature = "exfat",
    feature = "btrfs",
    feature = "apfs"
))]
mod open;
#[cfg(any(
    feature = "ext",
    feature = "fat",
    feature = "exfat",
    feature = "btrfs",
    feature = "apfs"
))]
pub use open::{FsReader, OpenError, open, open_with};

// What a format could not hold and what a read had to invent, both directions in one
// report, plus the values a read fills a missing field from.
mod fidelity;
pub use fidelity::{AcceptedLoss, Direction, FidelityRecord, FidelityReport, Property, Synthesis};

// The extraction surface: the four operations a sink needs of any family's reader, and the
// one behavioural trait the families share.
mod tree;
pub use tree::{Attributes, Bound, Child, FsTree, NodeKind, TreeEntry, TreeError, Usage};

// A tree this crate reads, handed back to the write side as a source.
mod image_source;
pub use image_source::{ImageFile, ImageSource};

// Room to leave when a filesystem is sized to its contents rather than told a size. What
// every family's search shares is the input and the arithmetic over it; the search itself
// is each family's, because a probe is that family's writer. Compiled where a family is:
// with none there is nothing to size.
#[cfg(any(
    feature = "ext",
    feature = "fat",
    feature = "exfat",
    feature = "btrfs",
    feature = "apfs"
))]
mod sizing;
#[cfg(any(
    feature = "ext",
    feature = "fat",
    feature = "exfat",
    feature = "btrfs",
    feature = "apfs"
))]
pub use sizing::Slack;

// A POSIX access control list, which is the value one extended attribute carries. Like
// `Xattr` itself it is boundary vocabulary: how tightly a family packs one is that family's
// business, and the value is not.
mod acl;
pub use acl::{Acl, AclEntry, AclError, AclQualifier};

// Where a tree comes from and where one goes: an archive at one end, a host directory at the
// other, each in both directions. They are concrete implementations of the root's own
// vocabulary rather than any family's — a sink drains whatever `open` returns, and a source
// feeds whichever family is being written — so they are named here and nowhere else.
#[cfg(feature = "tar")]
mod archive;
#[cfg(feature = "tar")]
pub use archive::{ArchiveError, ArchiveSink, ArchiveSource};
#[cfg(all(feature = "dir", any(target_os = "linux", target_os = "android")))]
mod host;
#[cfg(all(feature = "dir", any(target_os = "linux", target_os = "android")))]
pub use host::{DirectorySink, DirectorySource, ExtractReport, HostError};

// ── The ext family: the `ext` module, behind the `ext` feature ──
//
// The family's modules live at the crate root as private modules — so their cross-module
// paths stay `crate::` — and are presented to callers only through [`ext`]. The feature
// model, the checksum seam, and the scan taxonomy are ext concepts: they are reached
// through `ext`, not the crate root.
#[cfg(feature = "ext")]
mod alloc;
#[cfg(feature = "ext")]
mod csum;
#[cfg(feature = "ext")]
mod dir;
#[cfg(feature = "ext")]
mod extent;
#[cfg(feature = "ext")]
mod feature;
#[cfg(feature = "ext")]
mod fit;
#[cfg(feature = "ext")]
mod geometry;
#[cfg(feature = "ext")]
mod hash;
#[cfg(feature = "ext")]
mod identity;
#[cfg(feature = "ext")]
mod journal;
#[cfg(feature = "ext")]
mod materialize;
#[cfg(feature = "ext")]
mod model;
#[cfg(feature = "ext")]
mod ondisk;
#[cfg(feature = "ext")]
mod read;
#[cfg(feature = "ext")]
mod replay;
#[cfg(feature = "ext")]
mod sealed;

#[cfg(feature = "ext")]
pub mod ext;

// ── The FAT family: the `fat` module, behind the `fat` feature ──
//
// A family of its own, sharing only the root substrate with ext. Its layers live under the
// module rather than at the crate root, so nothing about a FAT boot sector is reachable
// without naming the family it belongs to.
#[cfg(feature = "fat")]
pub mod fat;

// ── The exFAT family: the `exfat` module, behind the `exfat` feature ──
//
// A family of its own, and not a member of the one it shares a name with: the two have a
// different boot region, a different directory entry format, a different name encoding, and
// an allocation model FAT has no equivalent of. Same arrangement as `fat` — the layers live
// under the module, so nothing about an exFAT boot sector is reachable without naming the
// family it belongs to.
#[cfg(feature = "exfat")]
pub mod exfat;

// ── The btrfs family: the `btrfs` module, behind the `btrfs` feature ──
//
// Same arrangement again, over a format built differently from all three above: B-trees over
// a logical address space that a chunk tree maps onto the device, with a checksum on every
// metadata block. The layers live under the module, so nothing about a chunk map is reachable
// without naming the family it belongs to.
#[cfg(feature = "btrfs")]
pub mod btrfs;

// ── The APFS family: the `apfs` module, behind the `apfs` feature ──
//
// A container of volumes rather than one filesystem: a pool of blocks under a checkpoint and
// an object map, listing up to a hundred volumes that each have a tree of their own. The
// layers live under the module, so nothing about a checkpoint is reachable without naming
// the family it belongs to.
#[cfg(feature = "apfs")]
pub mod apfs;