xfs_inode.hpp

Go to the documentation of this file.

// xfs_inode.hpp -- XFS dinode parsing.
//
// A "dinode" is XFS's on-disk inode structure. Its size is fixed per
// filesystem (typically 256, 512, 1024, or 2048 bytes -- sb.inodesize)
// and it lives at a fixed disk byte offset that the IBT walker has
// already given us as `AllocatedInode.disk_offset`.
//
// Structure of a dinode:
//
//   [ core (~100 bytes) ]
//   [ data fork content ] -- format depends on di_format
//   [ attribute fork    ] -- optional, located at di_forkoff*8 from end of core
//
// Core (V3, the modern V5 format):
//
//   offset  size  field
//   0x00    2     di_magic        "IN" (0x494E)  big-endian
//   0x02    2     di_mode         POSIX mode (file type + permissions)
//   0x04    1     di_version      1, 2, or 3 (V3 = V5 inode)
//   0x05    1     di_format       1=local, 2=extents, 3=btree, 4=uuid (legacy)
//   0x06    2     di_onlink       (legacy V1 only; pad on V2/V3)
//   0x08    4     di_uid
//   0x0C    4     di_gid
//   0x10    4     di_nlink        V2/V3
//   0x14    2     di_projid_lo
//   0x16    2     di_projid_hi
//   0x18    8     di_pad[]        (8 bytes pad)
//   0x20    2     di_flushiter    bumped at write
//   0x22    2     reserved
//   0x24    8     di_atime        sec(4) + nsec(4)
//   0x2C    8     di_mtime
//   0x34    8     di_ctime
//   0x3C    8     di_size         (logical file size in bytes)
//   0x44    8     di_nblocks
//   0x4C    4     di_extsize
//   0x50    4     di_nextents     (number of data-fork extents)
//   0x54    2     di_anextents    (number of attribute-fork extents)
//   0x56    1     di_forkoff      (in 8-byte units; 0 = no attribute fork)
//   0x57    1     di_aformat
//   0x58    4     di_dmevmask
//   0x5C    2     di_dmstate
//   0x5E    2     di_flags
//   0x60    4     di_gen
//   0x64    4     di_next_unlinked  -- last byte of V1/V2 core
//
// V3-specific extension (only if di_version == 3):
//   0x68    4     di_crc            CRC32 of the dinode
//   0x6C    8     di_changecount
//   0x74    8     di_lsn
//   0x7C    8     di_flags2
//   0x84    4     di_cowextsize
//   0x88    12    di_pad2[]
//   0x94    8     di_crtime         (creation time)
//   0x9C    8     di_ino            (inode number, redundant copy)
//   0xA4    16    di_uuid           (volume uuid copy)
//
// V3 core ends at offset 0xB4 = 180 bytes. The data fork starts there.
// V2/V1 core ends at offset 0x68 = 104 bytes.
//
// EXTENT RECORDS (di_format=2)
// ----------------------------
// An extent record is exactly 16 bytes and is bit-packed across two
// 64-bit big-endian words. Layout (bit 0 = MSB):
//
//   word0[63]      flag (0 = normal extent, 1 = unwritten preallocated)
//   word0[62..9]   logical offset (54 bits) -- in filesystem blocks
//   word0[8..0]    upper 9 bits of physical block (out of 52)
//   word1[63..21]  lower 43 bits of physical block (so 9+43 = 52 total)
//   word1[20..0]   length in blocks (21 bits)
//
// Decoding requires careful big-endian handling and shift counts. We
// expose `decode_extent_record(bytes16, out_extent)` and unit-test it.
//
// Inline data:
//   For di_format == 1 (local), the data fork is just bytes -- e.g. for a
//   shortform directory, those are the SF directory entries; for a small
//   symlink, those are the link target string; for a tiny file with
//   inline data... actually XFS does NOT inline file data the way ext4
//   does. di_format=1 for a regular file is essentially never seen in
//   practice (XFS allocates an extent even for empty files). What is
//   commonly inlined:
//     - Shortform symlinks (mode S_IFLNK + di_format=1)
//     - Shortform directories (mode S_IFDIR + di_format=1)
//   We handle both.
 
#pragma once
 
#include "xfs_format.hpp"
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace xfs {
 
// di_format values
constexpr uint8_t XFS_DINODE_FMT_DEV     = 0; // character/block device
constexpr uint8_t XFS_DINODE_FMT_LOCAL   = 1; // inline (shortform dir, symlink)
constexpr uint8_t XFS_DINODE_FMT_EXTENTS = 2; // extent list
constexpr uint8_t XFS_DINODE_FMT_BTREE   = 3; // extent B+tree (large/fragmented)
constexpr uint8_t XFS_DINODE_FMT_UUID    = 4; // legacy
 
// POSIX mode bits we actually look at
constexpr uint16_t MODE_TYPE_MASK = 0xF000;
constexpr uint16_t MODE_IFREG     = 0x8000;
constexpr uint16_t MODE_IFDIR     = 0x4000;
constexpr uint16_t MODE_IFLNK     = 0xA000;
constexpr uint16_t MODE_IFCHR     = 0x2000;
constexpr uint16_t MODE_IFBLK     = 0x6000;
constexpr uint16_t MODE_IFIFO     = 0x1000;
constexpr uint16_t MODE_IFSOCK    = 0xC000;
 
constexpr uint16_t XFS_DINODE_MAGIC_BE = 0x494E; // "IN"
 
struct DinodeCore {
    uint16_t magic        {0};
    uint16_t mode         {0};
    uint8_t  version      {0};
    uint8_t  format       {0};
    uint32_t uid          {0};
    uint32_t gid          {0};
    uint32_t nlink        {0};
    int64_t  size         {0};
    uint64_t nblocks      {0};
    uint32_t nextents     {0};
    uint16_t anextents    {0};
    uint8_t  forkoff      {0};   // attribute fork offset, in 8-byte units
    uint8_t  aformat      {0};
    uint16_t flags        {0};
    uint32_t gen          {0};
 
    // V3 only -- zero on V1/V2
    uint64_t ino          {0};
    uint64_t flags2       {0};
 
    // ---- helpers ----
    bool is_v3() const { return version == 3; }
    bool is_dir()      const { return (mode & MODE_TYPE_MASK) == MODE_IFDIR; }
    bool is_reg()      const { return (mode & MODE_TYPE_MASK) == MODE_IFREG; }
    bool is_symlink()  const { return (mode & MODE_TYPE_MASK) == MODE_IFLNK; }
    bool is_special()  const {
        const uint16_t t = mode & MODE_TYPE_MASK;
        return t == MODE_IFCHR || t == MODE_IFBLK ||
               t == MODE_IFIFO || t == MODE_IFSOCK;
    }
};
 
// Parse the core portion of a dinode from a raw buffer (must be at least
// inode_size bytes). Returns false on bad magic / impossible values.
bool parse_dinode_core(const unsigned char* buf, DinodeCore& out);
 
// Returns the byte offset within the inode where the data fork begins.
// V3 inode: 176 (0xB0). V1/V2 inode: 100 (0x64).
inline uint32_t dinode_data_fork_offset(const DinodeCore& core) {
    return core.is_v3() ? 176u : 100u;
}
 
// Returns the maximum byte length of the data fork (limited by attribute
// fork position when present, otherwise inode_size).
//
// `inode_size` is sb.inodesize (e.g. 256/512/1024/2048).
uint32_t dinode_data_fork_length(const DinodeCore& core, uint32_t inode_size);
 
// =============================================================================
// Extent records (bmbt records)
// =============================================================================
 
struct Extent {
    uint64_t logical_off_blocks {0};  // in filesystem blocks
    uint64_t physical_block     {0};  // global filesystem block number
    uint32_t length_blocks      {0};  // length in blocks
    bool     unwritten          {false};
};
 
// Decode one 16-byte BMBT extent record. The encoding is bit-packed
// across two 64-bit big-endian words (see header banner above).
void decode_extent_record(const unsigned char* buf16, Extent& out);
 
// Convert a "filesystem block number" (FSB) -- which encodes both AG
// number and AG-relative block in the high/low halves -- to an absolute
// disk byte offset. This is the formula:
//
//   agno  = fsb >> sb.agblklog
//   agbno = fsb & ((1 << sb.agblklog) - 1)
//   disk_offset = volume_offset + agno*agblocks*blocksize + agbno*blocksize
uint64_t fsb_to_disk_offset(uint64_t fsb, const VolumeContext& vol);
 
// Decode all extents in a data fork that has di_format=2.
// `data_fork_buf` points to the first extent record; `nextents` from
// the dinode core says how many to read; `max_bytes` is the max safe
// read length (data_fork_length).
//
// Returns false if `nextents * 16 > max_bytes` (corrupt inode).
bool decode_extents_inline(const unsigned char* data_fork_buf,
                           uint32_t nextents,
                           uint32_t max_bytes,
                           std::vector<Extent>& out);
 
} // namespace xfs