xfs_format.hpp

1. Overview

The xfs_format.hpp file defines XFS constants, packed metadata layouts and endian helpers.

This is an interface and data-contract file. It declares the public and internal types used by this subsystem, allowing implementation files and callers to share a stable compile-time contract.

Its paired source or interface file is xfs_format.cpp.

Primary responsibilities:

  • Describe superblocks, allocation groups and inodes
  • Define directory and B-tree structures
  • Centralize feature flags and magic values

2. File Identity and Scope

  • Source path: src/xfs_format.hpp
  • Language: C++
  • File role: interface and data-contract file
  • Physical lines: 324
  • Non-empty lines: 291
  • SHA-256: fe4622a26f3ecbf7383df31e65fcf4c0a903025ea1a8c7cc1f7e66bc11e88447

Declared namespaces:

  • xfs

3. Dependencies

3.2 Standard and External Headers

  • array
  • cstdint
  • cstddef
  • string
  • vector

These dependencies define the file’s compile-time integration with the recovery engine, GTK interface, on-disk format decoders, operating-system services, or C++ standard library.

4. Declared Types

  • struct Superblock.
  • struct AGF.
  • struct AGI.
  • struct InodeAddress.
  • struct AGContext.
  • struct VolumeContext.

5. Constants and Configuration Values

  • constexpr uint32_t XFS_SB_MAGIC=0x58465342u
  • constexpr uint32_t XFS_AGF_MAGIC_V4=0x58414746u
  • constexpr uint32_t XFS_AGF_MAGIC_V5=0x58414746u
  • constexpr uint32_t XFS_AGI_MAGIC_V4=0x58414749u
  • constexpr uint32_t XFS_AGI_MAGIC_V5=0x58414749u
  • constexpr uint32_t XFS_AGFL_MAGIC_V5=0x5841464Cu
  • constexpr uint32_t XFS_DINODE_MAGIC=0x494Eu
  • constexpr uint32_t XFS_ABTB_MAGIC_V4=0x41425442u
  • constexpr uint32_t XFS_ABTB_MAGIC_V5=0x41423342u
  • constexpr uint32_t XFS_ABTC_MAGIC_V4=0x41425443u
  • constexpr uint32_t XFS_ABTC_MAGIC_V5=0x41423343u
  • constexpr uint32_t XFS_IBT_MAGIC_V4=0x49414254u
  • constexpr uint32_t XFS_IBT_MAGIC_V5=0x49414233u
  • constexpr uint32_t XFS_FIBT_MAGIC_V4=0x46494254u
  • constexpr uint32_t XFS_FIBT_MAGIC_V5=0x46494233u
  • constexpr uint32_t XFS_BMAP_MAGIC_V4=0x424D4150u
  • constexpr uint32_t XFS_BMAP_MAGIC_V5=0x424D4133u
  • constexpr uint16_t XFS_SB_VERSION_NUMBITS=0x000F
  • constexpr uint16_t XFS_SB_VERSION_4=4
  • constexpr uint16_t XFS_SB_VERSION_5=5
  • constexpr uint16_t XFS_SB_VERSION_ATTRBIT=0x0010
  • constexpr uint16_t XFS_SB_VERSION_NLINKBIT=0x0020
  • constexpr uint16_t XFS_SB_VERSION_QUOTABIT=0x0040
  • constexpr uint16_t XFS_SB_VERSION_ALIGNBIT=0x0080
  • constexpr uint16_t XFS_SB_VERSION_DALIGNBIT=0x0100
  • constexpr uint16_t XFS_SB_VERSION_SHAREDBIT=0x0200
  • constexpr uint16_t XFS_SB_VERSION_LOGV2BIT=0x0400
  • constexpr uint16_t XFS_SB_VERSION_SECTORBIT=0x0800
  • constexpr uint16_t XFS_SB_VERSION_EXTFLGBIT=0x1000
  • constexpr uint16_t XFS_SB_VERSION_DIRV2BIT=0x2000
  • constexpr uint16_t XFS_SB_VERSION_BORGBIT=0x4000
  • constexpr uint16_t XFS_SB_VERSION_MOREBITSBIT=0x8000
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_FINOBT=0x00000001
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_RMAPBT=0x00000002
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_REFLINK=0x00000004
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_INOBTCNT=0x00000008
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_FTYPE=0x00000001
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_SPINODES=0x00000002
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_META_UUID=0x00000004
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_BIGTIME=0x00000008
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_NEEDSREPAIR=0x00000010
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_NREXT64=0x00000020

5.1 Operational Strings, Paths, Formats, or Commands

The following code literals are operationally relevant and may identify filesystem paths, helper commands, formats, signatures, or subsystem labels:

  • XFS Algorithms & Data Structures, 3rd Edition
  • XFSB

6. Data Members and Persistent State

The interface declares the following state-bearing members:

  • constexpr uint32_t XFS_SB_MAGIC=0x58465342u
  • constexpr uint32_t XFS_AGF_MAGIC_V4=0x58414746u
  • constexpr uint32_t XFS_AGF_MAGIC_V5=0x58414746u
  • constexpr uint32_t XFS_AGI_MAGIC_V4=0x58414749u
  • constexpr uint32_t XFS_AGI_MAGIC_V5=0x58414749u
  • constexpr uint32_t XFS_AGFL_MAGIC_V5=0x5841464Cu
  • constexpr uint32_t XFS_DINODE_MAGIC=0x494Eu
  • constexpr uint32_t XFS_ABTB_MAGIC_V4=0x41425442u
  • constexpr uint32_t XFS_ABTB_MAGIC_V5=0x41423342u
  • constexpr uint32_t XFS_ABTC_MAGIC_V4=0x41425443u
  • constexpr uint32_t XFS_ABTC_MAGIC_V5=0x41423343u
  • constexpr uint32_t XFS_IBT_MAGIC_V4=0x49414254u
  • constexpr uint32_t XFS_IBT_MAGIC_V5=0x49414233u
  • constexpr uint32_t XFS_FIBT_MAGIC_V4=0x46494254u
  • constexpr uint32_t XFS_FIBT_MAGIC_V5=0x46494233u
  • constexpr uint32_t XFS_BMAP_MAGIC_V4=0x424D4150u
  • constexpr uint32_t XFS_BMAP_MAGIC_V5=0x424D4133u
  • constexpr uint16_t XFS_SB_VERSION_NUMBITS=0x000F
  • constexpr uint16_t XFS_SB_VERSION_4=4
  • constexpr uint16_t XFS_SB_VERSION_5=5
  • constexpr uint16_t XFS_SB_VERSION_ATTRBIT=0x0010
  • constexpr uint16_t XFS_SB_VERSION_NLINKBIT=0x0020
  • constexpr uint16_t XFS_SB_VERSION_QUOTABIT=0x0040
  • constexpr uint16_t XFS_SB_VERSION_ALIGNBIT=0x0080
  • constexpr uint16_t XFS_SB_VERSION_DALIGNBIT=0x0100
  • constexpr uint16_t XFS_SB_VERSION_SHAREDBIT=0x0200
  • constexpr uint16_t XFS_SB_VERSION_LOGV2BIT=0x0400
  • constexpr uint16_t XFS_SB_VERSION_SECTORBIT=0x0800
  • constexpr uint16_t XFS_SB_VERSION_EXTFLGBIT=0x1000
  • constexpr uint16_t XFS_SB_VERSION_DIRV2BIT=0x2000
  • constexpr uint16_t XFS_SB_VERSION_BORGBIT=0x4000
  • constexpr uint16_t XFS_SB_VERSION_MOREBITSBIT=0x8000
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_FINOBT=0x00000001
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_RMAPBT=0x00000002
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_REFLINK=0x00000004
  • constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_INOBTCNT=0x00000008
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_FTYPE=0x00000001
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_SPINODES=0x00000002
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_META_UUID=0x00000004
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_BIGTIME=0x00000008
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_NEEDSREPAIR=0x00000010
  • constexpr uint32_t XFS_SB_FEAT_INCOMPAT_NREXT64=0x00000020
  • uint32_t magicnum {0}
  • uint32_t blocksize {0}
  • uint64_t dblocks {0}
  • uint64_t rblocks {0}
  • uint64_t rextents {0}
  • std::array<uint8_t,16> uuid {}
  • uint64_t logstart {0}
  • uint64_t rootino {0}
  • uint64_t rbmino {0}
  • uint64_t rsumino {0}
  • uint32_t rextsize {0}
  • uint32_t agblocks {0}
  • uint32_t agcount {0}
  • uint32_t rbmblocks {0}
  • uint32_t logblocks {0}
  • uint16_t versionnum {0}
  • uint16_t sectsize {0}
  • uint16_t inodesize {0}
  • uint16_t inopblock {0}
  • std::array<char,12> fname {}
  • uint8_t blocklog {0}
  • uint8_t sectlog {0}
  • uint8_t inodelog {0}
  • uint8_t inopblog {0}
  • uint8_t agblklog {0}
  • uint8_t rextslog {0}
  • uint8_t inprogress {0}
  • uint8_t imax_pct {0}
  • uint64_t icount {0}
  • uint64_t ifree {0}
  • uint64_t fdblocks {0}
  • uint64_t frextents {0}
  • uint64_t uquotino {0}
  • uint64_t gquotino {0}
  • uint16_t qflags {0}
  • uint8_t flags {0}
  • uint8_t shared_vn {0}
  • uint32_t inoalignmt {0}
  • uint32_t unit {0}
  • uint32_t width {0}
  • uint8_t dirblklog {0}
  • uint8_t logsectlog {0}
  • uint16_t logsectsize {0}
  • uint32_t logsunit {0}
  • uint32_t features2 {0}
  • uint32_t bad_features2 {0}
  • uint32_t features_compat {0}
  • uint32_t features_ro_compat {0}
  • uint32_t features_incompat {0}
  • uint32_t features_log_incompat {0}
  • uint32_t crc {0}
  • uint32_t spino_align {0}
  • uint64_t pquotino {0}
  • uint64_t lsn {0}
  • std::array<uint8_t,16> meta_uuid {}
  • uint32_t versionnum {0}
  • uint32_t seqno {0}
  • uint32_t length {0}
  • uint32_t flfirst {0}
  • uint32_t fllast {0}
  • uint32_t flcount {0}
  • uint32_t freeblks {0}
  • uint32_t longest {0}
  • uint32_t btreeblks {0}
  • uint32_t count {0}
  • uint32_t root {0}
  • uint32_t level {0}
  • uint32_t freecount {0}
  • uint32_t newino {0}
  • uint32_t dirino {0}
  • uint32_t free_root {0}
  • uint32_t free_level {0}
  • uint32_t agno {0}
  • uint32_t agbno {0}
  • uint32_t offset {0}
  • bool agf_loaded {false}
  • bool agi_loaded {false}
  • AGF agf {}
  • AGI agi {}
  • Superblock sb {}
  • uint64_t volume_offset {0}
  • std::vector<AGContext> ag {}

These members hold configuration, parser context, UI widgets, source references, progress state, recovered metadata, or temporary resources according to the owning type.

7. API and Function Inventory

The following callable interfaces or definitions were detected:

  • inline uint16_t be16(const unsigned char*p) – Implements the operation identified by this API and updates or returns the associated state.
  • inline uint32_t be32(const unsigned char*p) – Implements the operation identified by this API and updates or returns the associated state.
  • inline uint64_t be64(const unsigned char*p) – Implements the operation identified by this API and updates or returns the associated state.
  • unsigned format_version()const – Implements the operation identified by this API and updates or returns the associated state.
  • bool is_v5()const – Evaluates the stated condition and returns the corresponding Boolean result.
  • bool is_v4()const – Evaluates the stated condition and returns the corresponding Boolean result.
  • bool has_crc()const – Evaluates the stated condition and returns the corresponding Boolean result.
  • bool has_ftype()const – Evaluates the stated condition and returns the corresponding Boolean result.
  • uint64_t volume_size_bytes()const – Implements the operation identified by this API and updates or returns the associated state.
  • std::string label()const – Implements the operation identified by this API and updates or returns the associated state.
  • bool parse_superblock(const unsigned char*buf,Superblock&out) – Reads or derives the requested information and returns or stores the decoded result.
  • bool parse_agf(const unsigned char*buf,AGF&out) – Reads or derives the requested information and returns or stores the decoded result.
  • bool parse_agi(const unsigned char*buf,AGI&out) – Reads or derives the requested information and returns or stores the decoded result.
  • bool parse_agi(const unsigned char*buf,bool is_v5,AGI&out) – Reads or derives the requested information and returns or stores the decoded result.
  • InodeAddress crack_inode(uint64_t ino,const Superblock&sb) – Implements the operation identified by this API and updates or returns the associated state.

8. Operational Flow

The subsystem represented by this file normally participates in the following flow:

  1. Describe superblocks, allocation groups and inodes.
  2. Define directory and B-tree structures.
  3. Centralize feature flags and magic values.
  4. Expose or execute the detected APIs: be16, be32, be64, format_version, is_v5, is_v4, has_crc, has_ftype, volume_size_bytes, label, parse_superblock, parse_agf, parse_agi, crack_inode.
  5. Return explicit results, progress data, recovered records, or diagnostics to the calling layer.

9. Validation and Error Handling

  • Byte offsets, sizes and lengths must be validated before arithmetic and before every read to avoid overflow and out-of-bounds access.
  • On-disk structures are accepted only after validating signatures, magic values and structural constraints.

10. Runtime, Concurrency, and Resource Management

  • Deterministic behavior: callers depend on explicit return values and stable data structures to distinguish successful recovery from partial or invalid results.
  • File descriptors and streams must be closed on success, cancellation and error paths.

11. Security and Data-Recovery Considerations

  • Recovery code should prefer read-only source access and avoid writing to the original damaged medium.
  • Raw devices and image files are treated as untrusted binary input; every offset and length must remain bounded by the source size.

12. Implementation Considerations

  • Changes to public declarations can affect every translation unit that includes this header and should preserve binary and source compatibility where required.
  • State-bearing members should have explicit ownership and initialization semantics, especially for references, pointers, file descriptors and GTK widgets.
  • Binary decoding uses low-level memory operations or casts; alignment, endianness and packed-structure assumptions require careful review.
  • Large-device arithmetic uses 64-bit values; additions and multiplications should be checked before use as offsets or allocation sizes.

13. Integration with the Recovery Pipeline

  • The file belongs to the source-discovery, parsing or support layer.
  • Its results feed scanner, recovery or reporting modules through shared models.
  • The API should remain deterministic so higher layers can combine results safely.

14. Licensing and Provenance

No explicit copyright or software-license statement was detected in the opening section of this individual file. Distribution terms should therefore be verified against the project-level license and repository metadata.

The SHA-256 value in this document can be used to associate the generated documentation with the exact source version analyzed.

Published on:
Last updated on: