Expand description
xfs-core — a pure-Rust, from-scratch XFS filesystem reader.
Parses the on-disk XFS structures a forensic tool needs — superblock and geometry, allocation-group headers, inodes, extents, and the five directory formats — over any byte source. The reader targets both v4 (legacy) and v5 (self-describing CRC-stamped) filesystems.
Import path is xfs (see [lib] name): use xfs::Superblock;.
§Safety and robustness
This crate parses untrusted, attacker-controllable disk images. It is
#![forbid(unsafe_code)] and every integer is read through bounds-checked
big-endian helpers that yield 0/None out of range rather than panic
(the Paranoid Gatekeeper standard).
Re-exports§
pub use crc::crc_status;pub use crc::verify_crc;
Modules§
- bytes
- Bounds-checked big-endian readers (the Paranoid Gatekeeper standard).
- crc
- v5 CRC32c self-describing-metadata verification (
xfs_verify_cksum).
Structs§
- Agf
- The AGF free-space header.
- Agfl
- The AGFL free-list block ring.
- Agi
- The AGI inode-allocation header.
- BmbtRec
- A decoded 16-byte
xfs_bmbt_recextent descriptor. - DirEntry
- A single directory entry: a name, the inode it points at, and — when the filesystem’s ftype feature is on — the on-disk file-type byte.
- Inode
- A parsed XFS inode core (
di_core), v2 or v3. - Inode
Location - The decoded location of an inode: its allocation group, in-AG coordinates, absolute filesystem block, and absolute byte position in the image.
- Superblock
- Parsed XFS superblock — geometry and the log2 shift fields the inode-number decode (P1) needs.
- XfsTimestamp
- A decoded inode timestamp: signed Unix seconds + nanoseconds.
Enums§
- File
Type - The
S_IFMTfile type decoded fromdi_mode. - Inode
Format - The data-fork format selector (
di_format/di_aformat). - XfsError
- Errors surfaced while parsing XFS on-disk structures.
Constants§
- MAX_
BMBT_ LEVELS - Maximum bmbt tree depth followed. Real bmbt trees are at most a handful of levels deep (the fanout is hundreds per block); a claimed depth beyond this is corrupt/hostile and the walk stops rather than recurse unboundedly.
- MAX_
BMBT_ PTRS - Maximum total block pointers the walk will follow across the whole tree — an allocation/DoS cap so a fabricated wide tree cannot make the walk run for an unbounded time or collect an unbounded number of records.
- XFS_
AGFL_ MAGIC - AGFL magic (v5 only) — ASCII
"XAFL". - XFS_
AGF_ MAGIC - AGF magic — ASCII
"XAGF". - XFS_
AGI_ MAGIC - AGI magic — ASCII
"XAGI". - XFS_
AGI_ UNLINKED_ BUCKETS - Number of
unlinkedhash buckets in an AGI. - XFS_
BMAP_ CRC_ MAGIC XFS_BMAP_CRC_MAGIC— a v5 (CRC) bmbt block, ASCII"BMA3".- XFS_
BMAP_ MAGIC XFS_BMAP_MAGIC— a v4 (non-CRC) bmbt block, ASCII"BMAP".- XFS_
DIFLA G2_ BIGTIME XFS_DIFLAG2_BIGTIME(bit 3) — set in v3di_flags2when timestamps use the 64-bit bigtime counter instead of the legacy(sec:i32, nsec:i32)pair.- XFS_
DINODE_ MAGIC - The XFS inode magic number, ASCII
"IN"at byte 0 (XFS_DINODE_MAGIC). - XFS_
DIR2_ BLOCK_ MAGIC - The v4 single-block directory data-block magic (
XFS_DIR2_BLOCK_MAGIC,"XD2B"). - XFS_
DIR2_ DATA_ MAGIC - The v4 multi-block directory data-block magic (
XFS_DIR2_DATA_MAGIC,"XD2D"). - XFS_
DIR3_ BLOCK_ MAGIC - The v5 single-block directory data-block magic (
XFS_DIR3_BLOCK_MAGIC,"XDB3"). - XFS_
DIR3_ DATA_ MAGIC - The v5 multi-block directory data-block magic (
XFS_DIR3_DATA_MAGIC,"XDD3"). A leaf/node directory’s DATA blocks carry this (distinct from the single-blockXDB3) and, unlike a single block, have NO block tail. - XFS_
SB_ MAGIC - The XFS superblock magic number, ASCII
"XFSB"at byte 0.
Functions§
- assemble_
extents - Reconstruct a file’s bytes from an already-decoded extent list.
- read_
block_ dir - Parse a single-block (block-format) directory from its raw data-block bytes.
- read_
btree_ extents - Walk a bmap B+tree given its inline
xfs_bmdr_blockroot (the inode data fork) and collect every leafxfs_bmbt_recin tree (startoff) order. - read_
by_ path - Read a file by its absolute path, navigating the directory tree from the root.
- read_
data_ dir_ block - Parse a MULTI-block directory data block (
XDD3v5 /XD2Dv4) from its raw bytes. - read_
dir - List a directory inode’s entries (free-function form of
Superblock::read_dir). - read_
extents - Decode up to
nextentsconsecutive 16-bytexfs_bmbt_recrecords from a data fork. Records past the end offorkare not read (bounds-stopping): a truncated or lyingnextentsyields only the records that fully fit, never an over-read. - read_
file_ from_ fork - Reconstruct an extent-list file’s bytes from its raw data fork.
- read_
shortform_ dir - Parse a short-form directory from its inode data fork.
- verify_
bmbt_ block_ crc - Verify the v5 CRC32c of an on-disk bmbt
block, returningSome(true/false)on a v5 (BMA3) block andNoneon a v4 (BMAP) block (no CRC). - verify_
dir_ block_ crc - Verify the v5 CRC32c of a directory
block(data, single-block, leaf, node, or freeindex), returningSome(true/false)on a v5 block andNoneon a v4 block (which carries no CRC).