header.h File Reference

On-disk container header structures (v1 and v2) for Aaru images. More...

Go to the source code of this file.

Data Structures
struct	AaruHeader
	Version 1 container header placed at offset 0 for legacy / initial format. More...
struct	AaruHeaderV2
	Version 2 container header with GUID, alignment shifts, and feature negotiation bitmaps. More...

Macros
#define	AARU_HEADER_APP_NAME_LEN   64
	Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).
#define	GUID_SIZE   16
	Size in bytes of GUID / UUID-like binary identifier.

Typedefs
typedef struct AaruHeader	AaruHeader
typedef struct AaruHeaderV2	AaruHeaderV2

Detailed Description

On-disk container header structures (v1 and v2) for Aaru images.

These packed headers appear at the very beginning (offset 0) of every Aaru image file and advertise container format version, creator application, indexing offset and optional extended feature capability bitfields (v2+). All multi-byte integers are little-endian. Strings stored in the fixed-size application field are UTF‑16LE and zero padded (not necessarily NUL-terminated if fully filled). The GUID field (v2) allows derivative / child images to reference an origin.

Version progression:

• v1: AaruHeader (no GUID, no alignment or shift metadata, no feature bitfields).
• v2: AaruHeaderV2 introduces GUID, block/data/table shift hints (mirroring DDT metadata), and three 64‑bit feature bitmaps to negotiate reader/writer compatibility.

Compatibility handling (recommended logic for consumers):

1. If any bit set in featureIncompatible is not implemented by the reader: abort (cannot safely read/write).
2. Else if any bit set in featureCompatibleRo is not implemented: allow read‑only operations.
3. Bits only present in featureCompatible but not implemented MAY be ignored for both read/write while still preserving round‑trip capability (writer should not clear unknown bits when re‑saving).

Alignment & shift semantics (duplicated here for quick reference, see DdtHeader2 for full details):

• blockAlignmentShift: underlying blocks are aligned to 2^blockAlignmentShift bytes.
• dataShift: data pointer / DDT entry low bits encode offsets modulo 2^dataShift sectors/items.
• tableShift: primary DDT entries span 2^tableShift logical sectors (0 implies single-level tables).

Invariants:

• identifier == AARU_MAGIC (external constant; not defined here).
• For v1: sizeof(AaruHeader) exact and indexOffset > 0 (indexOffset == 0 => corrupt/unreadable image).
• For v2: sizeof(AaruHeaderV2) exact; indexOffset > 0; blockAlignmentShift, dataShift, tableShift within sane bounds (e.g. < 63). Zero is permissible only for the shift fields (not for indexOffset).

Security / robustness considerations:

• Always bounds-check indexOffset against file size before seeking.
• Treat application field as untrusted UTF‑16LE; validate surrogate pairs if necessary.
• Unknown feature bits MUST be preserved if a file is rewritten to avoid capability loss.

Definition in file header.h.

Macro Definition Documentation

AARU_HEADER_APP_NAME_LEN

#define AARU_HEADER_APP_NAME_LEN   64

Size in bytes (UTF-16LE) of application name field (32 UTF-16 code units).

Definition at line 59 of file header.h.

Referenced by aaruf_create(), and aaruf_open().

GUID_SIZE

#define GUID_SIZE   16

Size in bytes of GUID / UUID-like binary identifier.

Definition at line 60 of file header.h.

Referenced by aaruf_create().

Typedef Documentation

AaruHeader

typedef struct AaruHeader AaruHeader

AaruHeaderV2

typedef struct AaruHeaderV2 AaruHeaderV2