libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
index.h File Reference

On‑disk index block header and entry structures (versions 1, 2 and 3). More...

Go to the source code of this file.

## Data Structures
struct | IndexHeader
| Index header (version 1) for legacy images (identifier == IndexBlock). More...
struct | IndexHeader2
| Index header (version 2) with 64‑bit entry counter (identifier == IndexBlock2). More...
struct | IndexHeader3
| Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3). More...
struct | IndexEntry
| Single index entry describing a block's type, (optional) data classification, and file offset. More...

## Typedefs
typedef struct IndexHeader | IndexHeader
typedef struct IndexHeader2 | IndexHeader2
typedef struct IndexHeader3 | IndexHeader3
typedef struct IndexEntry | IndexEntry

## Detailed Description

On‑disk index block header and entry structures (versions 1, 2 and 3).

The index provides a directory of all blocks contained in an Aaru image. Each index block starts with a versioned header (IndexHeader / IndexHeader2 / IndexHeader3) followed by a contiguous array of fixed‑size IndexEntry records. Version 3 adds support for hierarchical (chained / nested) subindexes.

Version mapping by block identifier (see BlockType):

- IndexBlock (v1) -> IndexHeader followed by 16‑bit entry count entries.
- IndexBlock2 (v2) -> IndexHeader2 followed by 64‑bit entry count entries.
- IndexBlock3 (v3) -> IndexHeader3 with optional hierarchical subindex references.

CRC coverage & endianness:

- The crc64 field stores a CRC64-ECMA over the entries array ONLY (header bytes are excluded).
- For images with imageMajorVersion <= AARUF_VERSION_V1 a legacy writer byte-swapped the CRC; readers compensate (see verify_index_v1/v2/v3). The value in the header remains whatever was originally written.

Hierarchical (v3) behavior:

- Entries whose blockType == IndexBlock3 refer to subindex blocks; readers recursively load and flatten.
- IndexHeader3::previous can point to a preceding index segment (for append / incremental scenarios) or 0.
- CRC of the main index does NOT cover subindex contents; each subindex has its own header + CRC.

Invariants / validation recommendations:

- identifier must equal the expected BlockType variant for that version.
- entries > 0 implies the entries array byte size == entries * sizeof(IndexEntry).
- crc64 must match recomputed CRC64( entries array ) (after legacy byte swap handling if required).
- For v3, if previous != 0 it should point to another IndexBlock3 header (optional best‑effort check).

Notes:

- Structures are packed (1‑byte alignment). All multi-byte integers are little‑endian on disk.
- The index does not store per-entry CRC; integrity relies on each individual block's own CRC plus the index CRC.
- dataType in IndexEntry is meaningful only for block types that carry typed data (e.g. DataBlock, DumpHardwareBlock, etc.).

See also: verify_index_v1(), verify_index_v2(), verify_index_v3() for integrity procedures.

Definition in file index.h.

## Typedef Documentation

## ◆ IndexEntry

typedef struct IndexEntry IndexEntry

## ◆ IndexHeader

typedef struct IndexHeader IndexHeader

## ◆ IndexHeader2

typedef struct IndexHeader2 IndexHeader2

## ◆ IndexHeader3

typedef struct IndexHeader3 IndexHeader3