index_v2.c File Reference

#include <limits.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include "aaruformat.h"
#include "log.h"
#include "utarray.h"

Go to the source code of this file.

Functions
UT_array *	process_index_v2 (aaruformat_context *ctx)
	Processes an index block (version 2) from the image stream.
int32_t	verify_index_v2 (aaruformat_context *ctx)
	Verifies the integrity of an index block (version 2) in the image stream.

Function Documentation

process_index_v2()

UT_array * process_index_v2

(

aaruformat_context *

ctx

)

Processes an index block (version 2) from the image stream.

Reads and parses an index block (version 2) from the image, returning an array of index entries. This function handles the intermediate index format used in mid-generation AaruFormat versions, providing compatibility with version 2 image files. It reads the IndexHeader2 structure followed by a sequential list of IndexEntry structures, validating the index identifier for format correctness.

Parameters

ctx	Pointer to the aaruformat context containing the image stream and header information.

Returns

Returns one of the following values:

Return values

UT_array*

Successfully processed the index block. This is returned when: The context and image stream are valid The index header is successfully read from the position specified in ctx->header.indexOffset The index identifier matches IndexBlock2 (version 2 format identifier) All index entries are successfully read and stored in the UT_array Memory allocation for the index entries array succeeds The returned array contains all index entries from the version 2 index block

NULL

Index processing failed. This occurs when: The context parameter is NULL The image stream (ctx->imageStream) is NULL or invalid Cannot read the IndexHeader2 structure from the image stream The index identifier doesn't match IndexBlock2 (incorrect format or corruption) Memory allocation fails for the UT_array structure File I/O errors occur while reading index entries

Note

Index Structure (Version 2):

• IndexHeader2: Contains identifier (IndexBlock2), entry count, and enhanced metadata
• IndexEntry array: Sequential list of entries describing block locations and types
• No CRC validation is performed during processing (use verify_index_v2 for validation)
• No compression support in version 2 index format
• Compatible with mid-generation AaruFormat improvements

Memory Management:

• Returns a newly allocated UT_array that must be freed by the caller using utarray_free()
• On error, any partially allocated memory is cleaned up before returning NULL
• Each IndexEntry is copied into the array (no reference to original stream data)

Version Compatibility:

• Supports only IndexBlock2 format (not IndexBlock or IndexBlock3)
• Compatible with intermediate AaruFormat image files
• Does not handle subindex or hierarchical index structures (introduced in v3)

Warning

The caller is responsible for freeing the returned UT_array using utarray_free(). Failure to free the array will result in memory leaks.

This function does not validate the CRC integrity of the index data. Use verify_index_v2() to ensure index integrity before processing.

The function assumes ctx->header.indexOffset points to a valid index block. Invalid offsets may cause file access errors or reading incorrect data.

Definition at line 81 of file index_v2.c.

References IndexHeader2::entries, FATAL, aaruformat_context::header, IndexHeader2::identifier, aaruformat_context::imageStream, IndexBlock2, AaruHeaderV2::indexOffset, and TRACE.

Referenced by aaruf_open(), and aaruf_verify_image().

verify_index_v2()

int32_t verify_index_v2

(

aaruformat_context *

ctx

)

Verifies the integrity of an index block (version 2) in the image stream.

Checks the CRC64 of the index block without decompressing it. This function performs comprehensive validation of the version 2 index structure including header validation, data integrity verification, and version-specific CRC calculation. It ensures the index block is valid and uncorrupted before the image can be safely used for data access.

Parameters

ctx	Pointer to the aaruformat context containing image stream and header information.

Returns

Returns one of the following status codes:

Return values

AARUF_STATUS_OK	(0) Successfully verified index integrity. This is returned when: The context and image stream are valid The index header is successfully read from ctx->header.indexOffset The index identifier matches IndexBlock2 (version 2 format) Memory allocation for index entries succeeds All index entries are successfully read from the image stream CRC64 calculation completes successfully with version-specific endianness handling The calculated CRC64 matches the expected CRC64 in the index header
AARUF_ERROR_NOT_AARUFORMAT	(-1) Invalid context or stream. This occurs when: The context parameter is NULL The image stream (ctx->imageStream) is NULL or invalid
AARUF_ERROR_CANNOT_READ_HEADER	(-6) Index header reading failed. This occurs when: Cannot read the complete IndexHeader2 structure from the image stream File I/O errors prevent accessing the header at ctx->header.indexOffset Insufficient data available at the specified index offset
AARUF_ERROR_CANNOT_READ_INDEX	(-19) Index format or data access errors. This occurs when: The index identifier doesn't match IndexBlock2 (wrong format or corruption) Cannot read all index entries from the image stream File I/O errors during index entry reading Index structure is corrupted or truncated
AARUF_ERROR_NOT_ENOUGH_MEMORY	(-9) Memory allocation failed. This occurs when: Cannot allocate memory for the index entries array System memory exhaustion prevents loading index data for verification
AARUF_ERROR_INVALID_BLOCK_CRC	(-18) CRC64 validation failed. This occurs when: The calculated CRC64 doesn't match the expected CRC64 in the index header Index data corruption is detected Data integrity verification fails indicating potential file damage

Note

CRC64 Validation Process:

• Reads all index entries into memory for CRC calculation
• Calculates CRC64 over the complete index entries array
• Applies version-specific endianness conversion for compatibility
• For imageMajorVersion <= AARUF_VERSION_V1: Uses bswap_64() for byte order correction
• Compares calculated CRC64 with the value stored in the IndexHeader2

Version 2 Enhancements:

• Uses IndexHeader2 structure with enhanced metadata support
• Maintains compatibility with legacy endianness handling
• Supports improved index entry organization compared to version 1

Memory Management:

• Allocates temporary memory for index entries during verification
• Automatically frees allocated memory on both success and error conditions
• Memory usage is proportional to the number of index entries

Verification Scope:

• Validates index header structure and identifier
• Verifies data integrity through CRC64 calculation
• Does not validate individual index entry contents or block references
• Does not check for logical consistency of referenced blocks

Warning

This function reads the entire index into memory for CRC calculation. Large indexes may require significant memory allocation.

The function assumes ctx->header.indexOffset points to a valid index location. Invalid offsets will cause file access errors or incorrect validation.

CRC validation failure indicates potential data corruption and may suggest the image file is damaged or has been modified outside of library control.

Definition at line 227 of file index_v2.c.

References aaruf_crc64_final(), aaruf_crc64_free(), aaruf_crc64_init(), aaruf_crc64_update(), AARUF_ERROR_CANNOT_READ_HEADER, AARUF_ERROR_CANNOT_READ_INDEX, AARUF_ERROR_INVALID_BLOCK_CRC, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_NOT_ENOUGH_MEMORY, AARUF_STATUS_OK, AARUF_VERSION_V1, bswap_64, IndexHeader2::crc64, IndexHeader2::entries, FATAL, aaruformat_context::header, IndexHeader2::identifier, AaruHeaderV2::imageMajorVersion, aaruformat_context::imageStream, IndexBlock2, AaruHeaderV2::indexOffset, and TRACE.

Referenced by aaruf_verify_image().