hfs_format.hpp

Go to the documentation of this file.

// hfs_format.hpp -- HFS+ / HFSX on-disk format definitions.
//
// References:
//   - Apple Technote TN1150: "HFS Plus Volume Format"
//     https://developer.apple.com/library/archive/technotes/tn/tn1150.html
//   - Linux kernel sources: fs/hfsplus/hfsplus_raw.h
//
// HFS+ is BIG-ENDIAN on disk (Mac/PowerPC heritage). All multi-byte
// integers in the structures below are stored big-endian. We provide
// be16/be32/be64 helpers in this header (mirror of xfs_format helpers,
// kept separate so the two filesystem implementations can evolve
// independently).
//
// VARIANTS:
//   * HFS+ classic: signature "H+" (0x482B), version 4
//                    case-insensitive comparison, NFD-normalised UTF-16
//   * HFSX:         signature "HX" (0x4858), version 5
//                    case-sensitive (or insensitive based on kHFSXKeyCompare),
//                    same on-disk layout otherwise
//   * Legacy HFS (no plus) is NOT supported here. It was effectively
//     replaced by HFS+ in 1998 and uses a completely different layout.
//
// VOLUME HEADER LOCATION:
//   The volume header lives at OFFSET 1024 from the volume start
//   (sector 2 with 512-byte sectors). A backup copy lives at
//   `volume_size - 1024` from the start (end-1024).
//
// THIS HEADER CONTAINS DEFINITIONS ONLY -- no implementation. The
// in-memory layout matches the on-disk layout where it makes sense
// (numeric fields), but we don't use packed structs for the whole
// thing because alignment of nested arrays is fragile across compilers.
// Instead, parse_volume_header() reads fields one by one with explicit
// big-endian decoders.
 
#pragma once
 
#include <array>
#include <cstdint>
#include <cstddef>
#include <string>
#include <vector>
 
namespace hfs {
 
// -----------------------------------------------------------------------------
//  Big-endian readers (HFS+ is big-endian on disk)
// -----------------------------------------------------------------------------
 
inline uint16_t be16(const unsigned char* p) {
    return static_cast<uint16_t>((p[0] << 8) | p[1]);
}
inline uint32_t be32(const unsigned char* p) {
    return (static_cast<uint32_t>(p[0]) << 24) |
           (static_cast<uint32_t>(p[1]) << 16) |
           (static_cast<uint32_t>(p[2]) << 8)  |
            static_cast<uint32_t>(p[3]);
}
inline uint64_t be64(const unsigned char* p) {
    return (static_cast<uint64_t>(p[0]) << 56) |
           (static_cast<uint64_t>(p[1]) << 48) |
           (static_cast<uint64_t>(p[2]) << 40) |
           (static_cast<uint64_t>(p[3]) << 32) |
           (static_cast<uint64_t>(p[4]) << 24) |
           (static_cast<uint64_t>(p[5]) << 16) |
           (static_cast<uint64_t>(p[6]) << 8)  |
            static_cast<uint64_t>(p[7]);
}
 
// -----------------------------------------------------------------------------
//  Magic & versioning
// -----------------------------------------------------------------------------
 
constexpr uint16_t HFSPLUS_SIGNATURE = 0x482B;  // "H+"
constexpr uint16_t HFSX_SIGNATURE    = 0x4858;  // "HX"
constexpr uint16_t HFSPLUS_VERSION   = 4;
constexpr uint16_t HFSX_VERSION      = 5;
 
// Volume header lives at this byte offset within the volume.
constexpr uint32_t HFSPLUS_VOLUME_HEADER_OFFSET = 1024;
 
// Volume attributes (selected -- see TN1150 for the full list)
constexpr uint32_t kHFSVolumeUnmountedBit         = (1u << 8);
constexpr uint32_t kHFSVolumeJournaledBit         = (1u << 13);
constexpr uint32_t kHFSVolumeSoftwareLockBit      = (1u << 15);
 
// Reserved file/folder catalog node IDs (CNIDs)
constexpr uint32_t kHFSRootParentID            = 1;
constexpr uint32_t kHFSRootFolderID            = 2;
constexpr uint32_t kHFSExtentsFileID           = 3;
constexpr uint32_t kHFSCatalogFileID           = 4;
constexpr uint32_t kHFSBadBlockFileID          = 5;
constexpr uint32_t kHFSAllocationFileID        = 6;
constexpr uint32_t kHFSStartupFileID           = 7;
constexpr uint32_t kHFSAttributesFileID        = 8;
constexpr uint32_t kHFSRepairCatalogFileID     = 14;
constexpr uint32_t kHFSBogusExtentFileID       = 15;
constexpr uint32_t kHFSFirstUserCatalogNodeID  = 16;
 
// -----------------------------------------------------------------------------
//  Forks
// -----------------------------------------------------------------------------
//
// A "fork" is a logical byte-stream of a file. HFS+ has data forks and
// resource forks; the special files use only the data fork. The on-disk
// representation contains:
//   __be64 logicalSize
//   __be32 clumpSize
//   __be32 totalBlocks
//   HFSPlusExtentRecord extents -- 8 entries of (startBlock, blockCount)
//
// Total size: 80 bytes. If the file has more than 8 extents, the
// remaining ones live in the Extents Overflow File (special file #3).
 
struct ForkExtent {
    uint32_t start_block {0};   // allocation-block-relative
    uint32_t block_count {0};
};
 
struct ForkData {
    uint64_t logical_size {0};
    uint32_t clump_size   {0};
    uint32_t total_blocks {0};
    std::array<ForkExtent, 8> extents {}; // inline extent record
};
 
// Parse 80 bytes into a ForkData.
bool parse_fork_data(const unsigned char* buf, ForkData& out);
 
// -----------------------------------------------------------------------------
//  Volume header
// -----------------------------------------------------------------------------
 
struct VolumeHeader {
    uint16_t signature       {0};     // "H+" or "HX"
    uint16_t version         {0};     // 4 (HFS+) / 5 (HFSX)
    uint32_t attributes      {0};
    uint32_t last_mounted_version {0};
    uint32_t journal_info_block   {0};
    uint32_t create_date     {0};     // local time, Mac epoch (1904-01-01)
    uint32_t modify_date     {0};
    uint32_t backup_date     {0};
    uint32_t checked_date    {0};
    uint32_t file_count      {0};
    uint32_t folder_count    {0};
    uint32_t block_size      {0};     // typically 4096 on modern volumes
    uint32_t total_blocks    {0};
    uint32_t free_blocks     {0};
    uint32_t next_allocation {0};
    uint32_t rsrc_clump_size {0};
    uint32_t data_clump_size {0};
    uint32_t next_catalog_id {0};
    uint32_t write_count     {0};
    uint64_t encodings_bitmap{0};
    std::array<uint8_t, 32> finder_info {};
 
    ForkData allocation_file {};
    ForkData extents_file    {};
    ForkData catalog_file    {};
    ForkData attributes_file {};
    ForkData startup_file    {};
 
    // ---- helpers ----
    bool is_hfsplus() const { return signature == HFSPLUS_SIGNATURE; }
    bool is_hfsx()    const { return signature == HFSX_SIGNATURE;   }
    bool is_journaled() const {
        return (attributes & kHFSVolumeJournaledBit) != 0;
    }
    uint64_t volume_size_bytes() const {
        return static_cast<uint64_t>(total_blocks) * block_size;
    }
    const char* variant_name() const {
        return is_hfsx() ? "HFSX" : (is_hfsplus() ? "HFS+" : "Unknown");
    }
};
 
// Parse a 512-byte sector containing the HFS+ / HFSX volume header.
// Returns false if signature is wrong or sanity checks fail.
//
// `buf` must point to at least 512 bytes (typically a sector at byte
// offset HFSPLUS_VOLUME_HEADER_OFFSET from the volume start).
bool parse_volume_header(const unsigned char* buf, VolumeHeader& out);
 
// Convert an allocation-block number to an absolute disk byte offset.
//   disk_offset = volume_offset + (alloc_block * block_size)
inline uint64_t alloc_block_to_disk_offset(uint64_t volume_offset,
                                           uint32_t alloc_block,
                                           uint32_t block_size) {
    return volume_offset + static_cast<uint64_t>(alloc_block) * block_size;
}
 
// -----------------------------------------------------------------------------
//  Volume context (parallels xfs::VolumeContext)
// -----------------------------------------------------------------------------
 
struct VolumeContext {
    VolumeHeader header {};
    uint64_t volume_offset {0};   // disk byte offset where the volume starts
    bool is_v5_hfsx {false};      // cached from header.signature
};
 
} // namespace hfs