xfs_dir.hpp

Go to the documentation of this file.

// xfs_dir.hpp -- XFS shortform directory parsing.
//
// Layout (reference: fs/xfs/libxfs/xfs_da_format.h in the Linux kernel):
//
//   struct xfs_dir2_sf_hdr {
//       __u8        count;     // entries excluding "." and ".."
//       __u8        i8count;   // entries that use 8-byte inode numbers
//       __u32_or_64 parent;    // parent inode (4 bytes if i8count==0, else 8)
//   };
//
//   struct xfs_dir2_sf_entry {
//       __u8 namelen;
//       __u8 offset[2];
//       __u8 name[namelen];
//       __u8 ftype;      // V5 only when SB has XFS_SB_FEAT_INCOMPAT_FTYPE
//       __u32_or_64 inumber;
//   };
//
// The "all 4 or all 8 bytes" rule is critical. If `i8count > 0`, every
// inode number in the directory (parent included) is 8 bytes. Otherwise,
// every inode number is 4 bytes. We honour this strictly.
//
// The pseudo-dirent offset (2 bytes after namelen) is for the older
// dir2 indexing scheme; we don't use it for recovery, but we have to
// skip those bytes correctly.
//
// FTYPE byte: present only when the volume's SB has the FTYPE feature
// flag. We get that flag from `Superblock::has_ftype()`.
 
#pragma once
 
#include "xfs_format.hpp"
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace xfs {
 
constexpr uint8_t XFS_DIR3_FT_UNKNOWN  = 0;
constexpr uint8_t XFS_DIR3_FT_REG_FILE = 1;
constexpr uint8_t XFS_DIR3_FT_DIR      = 2;
constexpr uint8_t XFS_DIR3_FT_CHRDEV   = 3;
constexpr uint8_t XFS_DIR3_FT_BLKDEV   = 4;
constexpr uint8_t XFS_DIR3_FT_FIFO     = 5;
constexpr uint8_t XFS_DIR3_FT_SOCK     = 6;
constexpr uint8_t XFS_DIR3_FT_SYMLINK  = 7;
 
// Block-format directory (single-block). The block contains:
//   header + data entries + (leaf tail at end -- we ignore it).
constexpr uint32_t XFS_DIR2_BLOCK_MAGIC = 0x58443242u; // "XD2B" (V4)
constexpr uint32_t XFS_DIR3_BLOCK_MAGIC = 0x58444233u; // "XDB3" (V5)
 
// Leaf-format directory: data blocks. The block contains:
//   header + data entries (no leaf tail; leaf is in a separate block range).
constexpr uint32_t XFS_DIR2_DATA_MAGIC  = 0x58443244u; // "XD2D" (V4)
constexpr uint32_t XFS_DIR3_DATA_MAGIC  = 0x58444433u; // "XDD3" (V5)
 
// Free-record sentinel inside a directory data block
constexpr uint16_t XFS_DIR2_DATA_FREE_TAG = 0xFFFFu;
 
struct DirEntry {
    std::string name;     // raw (NOT yet sanitized for host FS)
    uint64_t    ino {0};  // global inode number
    uint8_t     ftype {XFS_DIR3_FT_UNKNOWN};  // valid only if SB has FTYPE
    bool        ftype_valid {false};
};
 
struct ShortformDir {
    uint64_t parent_ino {0};
    std::vector<DirEntry> entries;  // does NOT include "." and ".."
};
 
// Parse a shortform directory. `data` points to the data fork content
// of the directory inode, `data_len` is its valid byte length, and
// `has_ftype` says whether each entry has a 1-byte ftype before the
// inumber (XFS_SB_FEAT_INCOMPAT_FTYPE).
//
// Returns false on malformed/truncated input. On success, `out` holds
// the parent inode and the list of entries.
bool parse_shortform_dir(const unsigned char* data,
                         uint32_t data_len,
                         bool has_ftype,
                         ShortformDir& out);
 
// =============================================================================
//  Block / leaf directory data-block parsing
// =============================================================================
//
// A "data block" of a block- or leaf-format directory has this layout:
//
//   [ header (V4: 16 bytes / V5: 64 bytes) ]
//   [ data entries OR unused (free) records, alternating ]
//   [ optional leaf-tail-table (only for BLOCK format -- we ignore it) ]
//
// Each data entry:
//   __be64 inumber
//   __u8   namelen
//   __u8   name[namelen]
//   __u8   ftype           (V5 + FTYPE feature only)
//   __be16 tag             (offset of entry start, used for indexing)
//   padding to 8-byte alignment of the NEXT record
//
// Each unused (free) record:
//   __be16 freetag = 0xFFFF
//   __be16 length  (length of this free hole, IN BYTES)
//   __be16 tag     (lookup pointer)
//
// Length of unused records is at least 16 bytes; the iterator skips
// them entirely.
//
// For block-format directories the trailing leaf table sits at the END
// of the block; we stop the iteration when we'd read into it. The leaf
// tail starts at an offset stored in the (V4) data_hdr.bestfree or in
// the V5 dir3_blk_tail; parsing it precisely is unnecessary for
// recovery -- a clean check `(rec_len == 0) || (offset + rec_len > tail_off)`
// is enough to stop safely.
//
// `block_buf` points to the start of the directory data block (block_size bytes).
// `is_v5` says which header layout to expect (40-byte dir3_blk_hdr+).
// `accept_block_magic` says whether to accept BLOCK magic (single-block dir);
// `accept_data_magic` whether to accept DATA magic (leaf-format data block).
//
// Returns false on bad magic / corrupted layout. Appends entries to `out`.
// Skips "." and ".." (recovery does not export them).
 
bool parse_dir_data_block(const unsigned char* block_buf,
                          uint32_t block_size,
                          bool is_v5,
                          bool has_ftype,
                          bool accept_block_magic,
                          bool accept_data_magic,
                          std::vector<DirEntry>& out);
 
} // namespace xfs