hfs_fork_io.hpp

Go to the documentation of this file.

// hfs_fork_io.hpp -- read fork content via inline extents.
//
// A "fork" in HFS+ has 8 inline extent descriptors stored in the fork
// data structure (HFSPlusForkData). For files / special files whose
// content fits in <= 8 extents, that's all we need to read the entire
// fork.
//
// In session 2 we ONLY support inline extents. Files with > 8 extents
// also have records in the Extents Overflow file (special file #3),
// which we will read in session 4.
//
// This file is the bridge between hfs_format.hpp (which defines the
// fork data structure) and the disk reader (which gives us bytes).
 
#pragma once
 
#include "hfs_format.hpp"
#include "disk_reader.hpp"
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace hfs {
 
// Read up to `max_bytes` from the start of a fork into `out`. Returns
// false if a read fails midway. Stops at the smaller of:
//   - the fork's logical_size
//   - the requested max_bytes
//   - the data covered by the 8 inline extents (a soft truncate is
//     treated as a non-fatal warning logged via `logs`)
//
// `volume_offset` is the disk byte offset where the HFS+ volume starts
// (0 for a raw image, partition_start for a partitioned disk).
//
// `block_size` is the volume's allocation block size from the volume
// header.
bool read_fork_inline(DiskReader& reader,
                      uint64_t volume_offset,
                      uint32_t block_size,
                      const ForkData& fork,
                      uint64_t max_bytes,
                      std::vector<unsigned char>& out,
                      std::vector<std::string>& logs);
 
// Read a single allocation block from a fork at the given byte offset
// inside the fork (logical, not physical). Walks the 8 inline extents
// to find which one contains `fork_logical_offset` and reads from
// there. Returns false on read failure or if the offset overflows the
// inline-extent coverage.
//
// `block_buf` must have size `block_size`. On success, exactly
// `block_size` bytes are written into it.
bool read_fork_block_inline(DiskReader& reader,
                             uint64_t volume_offset,
                             uint32_t block_size,
                             const ForkData& fork,
                             uint64_t fork_logical_offset,
                             unsigned char* block_buf);
 
// =============================================================================
//  Extents Overflow file (session 4)
// =============================================================================
//
// When a fork has more than 8 extents, the first 8 are stored inline in
// the catalog record's HFSPlusForkData; the rest live in records of the
// Extents Overflow B-tree (special file #3, vh.extents_file).
//
// Key layout (10 bytes after the 2-byte keyLength):
//   __u8   forkType    -- 0x00 = data fork, 0xFF = resource fork
//   __u8   pad
//   __be32 fileID
//   __be32 startBlock  -- the FIRST logical block this record covers
//
// Records are leaf-only; each leaf record body is exactly 64 bytes:
//   HFSPlusExtentRecord = ForkExtent[8]
//
// For a file whose data fork has N > 8 extents:
//   - Records 0..7 inline in catalog
//   - Records 8..15 in overflow with key startBlock = 8
//   - Records 16..23 in overflow with key startBlock = 16
//   - ...
// (the startBlock in the key counts BLOCKS, not bytes -- it's the
//  cumulative block count NOT the actual physical block number.)
 
constexpr uint8_t kForkTypeData     = 0x00;
constexpr uint8_t kForkTypeResource = 0xFF;
 
struct ExtentsOverflowKey {
    uint8_t  forkType   {0};
    uint32_t fileID     {0};
    uint32_t startBlock {0};
};
 
// Read up to `max_bytes` from a fork using BOTH inline extents and the
// Extents Overflow file. Equivalent to read_fork_inline() except that
// when a file has > 8 extents, the additional extents are looked up
// in the overflow B-tree.
//
// `extents_file` is the volume's vh.extents_file (the overflow B-tree
// content). We load it lazily via read_fork_inline() on first use.
//
// `extents_btree_buffer` (in/out): set to empty initially; the function
// fills it on the first call by reading the overflow file and reuses it
// on subsequent calls. This avoids re-reading the (possibly large)
// overflow file once per recovered file.
//
// `forkType`: kForkTypeData or kForkTypeResource.
// `fileID`: the file's CNID (HFSPlusCatalogFile.fileID).
//
// Returns true on success. If the overflow file itself can't be loaded,
// the function falls back to the inline extents and logs a warning.
bool read_fork_full(DiskReader& reader,
                    uint64_t volume_offset,
                    uint32_t block_size,
                    const ForkData& fork,
                    const ForkData& extents_file,
                    uint8_t forkType,
                    uint32_t fileID,
                    uint64_t max_bytes,
                    std::vector<unsigned char>& extents_btree_buffer,
                    std::vector<unsigned char>& out,
                    std::vector<std::string>& logs);
 
} // namespace hfs