mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 19:24:40 +00:00
55 lines
2.2 KiB
Plaintext
55 lines
2.2 KiB
Plaintext
=== Index Block Version 3 (`IDX3`)
|
|
|
|
Version 3 of the index structure introduces a new field: `previous`. This field enables any index block to reference another, allowing for non-linear and flexible index placement within the file.
|
|
|
|
This enhancement permits index blocks to be written at arbitrary offsets. If the current index is not the initial one, the `previous` field stores a pointer to the preceding index block, forming a linked chain of indexes.
|
|
|
|
In scenarios where the file cannot be finalized correctly—due to crashes, write interruptions, or failure to update the master header—the index chain allows reconstruction of the indexing structure. By scanning backward from the end of the file to locate the last written index and following each `previous` pointer, earlier indexes can be discovered and parsed.
|
|
|
|
This mechanism significantly improves fault tolerance. Unlike earlier versions where a partially written file could render indexing unusable, version 3 allows for resilient recovery and continued access to indexed data.
|
|
|
|
The index block in version 3 is immediately followed by index entries that maintain the same format as those defined in version 2, ensuring compatibility and easing transition between versions.
|
|
|
|
Index entries can contain *at most* a single child index pointer.
|
|
|
|
==== Structure Definition
|
|
|
|
[source,c]
|
|
/**Header for the index, followed by entries */
|
|
typedef struct IndexHeader3
|
|
{
|
|
uint32_t identifier; ///< Block identifier (must be BlockType::IndexBlock3).
|
|
uint64_t entries; ///< Number of \ref IndexEntry records that follow in this (sub)index block.
|
|
uint64_t crc64; ///< CRC64-ECMA of the local entries array (does NOT cover subindexes or previous chains).
|
|
uint64_t previous; ///< File offset of a previous IndexBlock3 header (0 if none / root segment).
|
|
} IndexHeader3;
|
|
|
|
==== Field Descriptions
|
|
|
|
[cols="2,2,2,6",options="header"]
|
|
|===
|
|
|Type
|
|
|Size
|
|
|Name
|
|
|Description
|
|
|
|
|uint32
|
|
|4 bytes
|
|
|identifier
|
|
|The index block identifier, always `IDX3`
|
|
|
|
|uint64
|
|
|8 bytes
|
|
|entries
|
|
|The number of entries following this header
|
|
|
|
|uint64
|
|
|8 bytes
|
|
|crc64
|
|
|CRC64-ECMA checksum of the entries following this header
|
|
|
|
|uint64
|
|
|8 bytes
|
|
|previous
|
|
|Pointer in image file to previous index block. `0` if this is the first index block.
|
|
|=== |