hfs_catalog.hpp

Go to the documentation of this file.

// hfs_catalog.hpp -- HFS+ catalog record body parsers.
//
// Reference: Apple TN1150, "HFS Plus Volume Format".
//
// Each leaf record in the catalog B-tree starts with a 2-byte big-endian
// recordType discriminator (right after the variable-length catalog
// key, aligned to a 16-bit boundary). Following the type:
//
//   * 0x0001 (kHFSPlusFolderRecord)        88-byte body: HFSPlusCatalogFolder
//   * 0x0002 (kHFSPlusFileRecord)         248-byte body: HFSPlusCatalogFile
//   * 0x0003 (kHFSPlusFolderThreadRecord)  variable body: thread record
//   * 0x0004 (kHFSPlusFileThreadRecord)    variable body: thread record
//
// Thread records hold (parentCNID, name) for reverse lookup
// (CNID -> path). They are NOT directory entries; folder/file records
// are. We don't need threads for the recovery tree walk: we already
// know the parent of every record from its catalog KEY (parentID is
// the parent CNID).
 
#pragma once
 
#include "hfs_format.hpp"
#include "hfs_btree.hpp"
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace hfs {
 
// HFSPlusBSDInfo (POSIX permissions, 16 bytes).
struct BSDInfo {
    uint32_t ownerID  {0};
    uint32_t groupID  {0};
    uint8_t  adminFlags {0};
    uint8_t  ownerFlags {0};
    uint16_t fileMode  {0};   // POSIX file mode (S_IFREG | 0644 etc.)
    uint32_t special   {0};   // device id for char/blk; iNode num for hardlinks
};
 
// FolderInfo / FileInfo "Finder info" (16 bytes).
// For files: fileType + fileCreator at offsets 0x00 and 0x04 (FourCC).
// For folders: window/scroll info, irrelevant to recovery.
struct FinderInfo16 {
    uint32_t fileType    {0};  // FourCC, e.g. 'slnk' for symlinks
    uint32_t fileCreator {0};  // FourCC, e.g. 'rhap' for symlinks
    uint16_t finderFlags {0};
    // The remaining 6 bytes are layout-specific; we don't need them.
};
 
// Symlink magic FourCCs (from /System/Library/Frameworks/...)
constexpr uint32_t kSymLinkFileType    = 0x736C6E6B; // 'slnk'
constexpr uint32_t kSymLinkCreator     = 0x72686170; // 'rhap'
// Hardlink magic FourCCs (these make a regular file act as a hardlink
// to an iNode file in HFS+ Private Data)
constexpr uint32_t kHardLinkFileType   = 0x686C6E6B; // 'hlnk'
constexpr uint32_t kHFSPlusCreator     = 0x6866732B; // 'hfs+'
 
// HFSPlusCatalogFolder body (88 bytes, NOT including the 2-byte
// recordType discriminator, which the caller has already read).
struct CatalogFolder {
    uint16_t flags        {0};
    uint32_t valence      {0};   // number of items in this folder
    uint32_t folderID     {0};   // CNID of this folder
    uint32_t createDate   {0};
    uint32_t contentModDate {0};
    uint32_t attributeModDate {0};
    uint32_t accessDate   {0};
    uint32_t backupDate   {0};
    BSDInfo  permissions  {};
    FinderInfo16 userInfo {};
    uint32_t textEncoding {0};
};
 
// HFSPlusCatalogFile body (248 bytes, NOT including recordType).
struct CatalogFile {
    uint16_t flags        {0};
    uint32_t fileID       {0};
    uint32_t createDate   {0};
    uint32_t contentModDate {0};
    uint32_t attributeModDate {0};
    uint32_t accessDate   {0};
    uint32_t backupDate   {0};
    BSDInfo  permissions  {};
    FinderInfo16 userInfo {};   // file: fileType + fileCreator
    uint32_t textEncoding {0};
    ForkData dataFork     {};
    ForkData resourceFork {};
 
    bool is_symlink() const {
        return userInfo.fileType == kSymLinkFileType &&
               userInfo.fileCreator == kSymLinkCreator;
    }
    bool is_hardlink() const {
        return userInfo.fileType == kHardLinkFileType &&
               userInfo.fileCreator == kHFSPlusCreator;
    }
};
 
// HFS+ catalog file flags (subset)
constexpr uint16_t kHFSFileLockedBit       = 0x0001;
constexpr uint16_t kHFSThreadExistsBit     = 0x0002;
constexpr uint16_t kHFSHasAttributesBit    = 0x0004;
constexpr uint16_t kHFSHasSecurityBit      = 0x0008;
constexpr uint16_t kHFSHasFolderCountBit   = 0x0010;
constexpr uint16_t kHFSHasLinkChainBit     = 0x0020;
constexpr uint16_t kHFSHasChildLinkBit     = 0x0040;
constexpr uint16_t kHFSHasDateAddedBit     = 0x0080;
 
// UF_COMPRESSED in BSDInfo.ownerFlags (== struct stat::st_flags bit)
// indicates a decmpfs-compressed file.
constexpr uint8_t  UF_COMPRESSED           = 0x20;
 
// =============================================================================
//  Hardlink helpers
// =============================================================================
//
// HFS+ implements POSIX hardlinks via "indirect node files" living
// under a hidden folder named "\x00\x00\x00\x00HFS+ Private Data" at
// the volume root. Each indirect node is a regular file named
// "iNode<NUM>", where <NUM> is a decimal number stored in the link's
// permissions.special field. The link's data fork is empty; its
// userInfo has fileType='hlnk' and fileCreator='hfs+'.
//
// Resolving a hardlink means:
//   1. The catalog has a "HFS+ Private Data" folder under root with
//      a special name (4 NUL bytes followed by "HFS+ Private Data")
//   2. Inside it, files "iNode1", "iNode2", ... contain the target's
//      data fork
//   3. We build a map iNode_num -> CatalogFile during the walk
//   4. When exporting a hardlink, we read the target's data fork
 
// The hidden folder's name as UTF-16 code units (BE on disk). 4 NUL +
// "HFS+ Private Data" = 4 + 17 = 21 code units.
constexpr int kHFSPrivateDataNameLength = 21;
 
// Returns true if `utf16be_name` (length `name_units`) matches the
// "HFS+ Private Data" folder name (4 leading NUL units).
bool is_private_data_folder_name(const unsigned char* utf16be_name,
                                  uint16_t name_units);
 
// Returns the iNode number embedded in a name like "iNode42"
// (UTF-16-BE code units). Returns 0 if the name doesn't match the
// pattern.
uint32_t parse_inode_filename(const unsigned char* utf16be_name,
                               uint16_t name_units);
 
// Parse the body of a folder record. `body` points to the byte AFTER
// the 2-byte recordType discriminator. `body_len` must be >= 88.
bool parse_catalog_folder(const unsigned char* body, uint32_t body_len,
                           CatalogFolder& out);
 
// Parse the body of a file record. `body` points to the byte AFTER
// the 2-byte recordType discriminator. `body_len` must be >= 248.
bool parse_catalog_file(const unsigned char* body, uint32_t body_len,
                         CatalogFile& out);
 
// =============================================================================
//  Record-by-parent index
// =============================================================================
//
// To walk the directory tree from rootCNID, we need to answer "what are
// the children of folder X?". HFS+ catalog records are KEYED by
// (parentCNID, name), so when we walk the leaf records we can build a
// multimap parent -> [child records].
//
// We don't store the entire record body in this index (memory waste);
// instead we store the minimal info needed to recurse:
//   - the child's NFC-converted name
//   - the recordType (folder vs file)
//   - the child's CNID
//   - for files: the dataFork (so we can read its content) and the
//     finderInfo (for symlink/hardlink detection)
 
struct ChildEntry {
    std::string name_nfc;
    int16_t  recordType {0};
 
    // Common to folders and files
    uint32_t cnid {0};
    uint16_t flags {0};       // HFSPlusCatalogFolder/File.flags
 
    // File-specific: only valid if recordType == kHFSPlusFileRecord
    ForkData dataFork {};
    ForkData resourceFork {};
    FinderInfo16 userInfo {};
    uint16_t fileMode {0};
    uint8_t  ownerFlags {0};  // BSD ownerFlags (UF_COMPRESSED bit)
    uint32_t special {0};     // BSDInfo.special (iNode num for hardlinks)
};
 
// Convert a UTF-16-BE name (from a CatalogKey) to NFC UTF-8, then
// sanitize for the host filesystem (replace illegal chars with '_').
std::string catalog_name_to_host(const unsigned char* utf16be_name,
                                  uint16_t name_units);
 
} // namespace hfs