#include <inttypes.h>
#include <limits.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include "aaruformat/context.h"
#include "aaruformat/errors.h"
#include "aaruformat/structs/index.h"
#include "consts.h"
#include "decls.h"
#include "log.h"
#include "utarray.h"
#include "uthash.h"

Data Structures
struct	FluxCaptureMapEntry
	Internal hash table entry for flux capture lookup. More...

Functions
static void	flux_capture_record_dtor (void *element)
	Destructor callback for FluxCaptureRecord elements in a utarray.
static void	flux_map_clear (aaruformat_context *ctx)
	Clear and deallocate the flux capture lookup map.
static int	flux_map_add (aaruformat_context ctx, const FluxCaptureKey key, uint32_t index)
	Add or update a flux capture entry in the lookup map.
int32_t	flux_map_rebuild_from_entries (aaruformat_context *ctx)
	Rebuild the flux capture lookup map from the flux_entries array.
void	process_flux_data_block (aaruformat_context ctx, const IndexEntry entry)
	Parse and integrate a Flux Data block from the image stream into the context.
static int32_t	ensure_flux_entries_loaded (aaruformat_context *ctx)
	Lazy load flux data block if not already loaded.
int32_t	aaruf_get_flux_captures (void context, uint8_t buffer, size_t *length)
	Retrieve metadata for all flux captures in the image.
int32_t	aaruf_write_flux_capture (void context, uint32_t head, uint16_t track, uint8_t subtrack, uint32_t capture_index, uint64_t data_resolution, uint64_t index_resolution, const uint8_t data, uint32_t data_length, const uint8_t *index, uint32_t index_length)
	Add a flux capture to the image during write mode.
int32_t	aaruf_clear_flux_captures (void *context)
	Clear all flux captures from the context.
static const FluxEntry *	find_flux_entry_by_key (const aaruformat_context ctx, const FluxCaptureKey key)
	Find a flux entry by its identifier key.
static int32_t	read_flux_payload_header (const aaruformat_context ctx, uint64_t payload_offset, DataStreamPayloadHeader header)
	Read and validate a flux payload block header from the image stream.
static int32_t	read_uncompressed_payload (const aaruformat_context ctx, size_t cmp_length, size_t raw_length, uint8_t cmp_buffer, uint8_t *payload)
	Read an uncompressed flux payload from the image stream.
static int32_t	read_lzma_compressed_payload (const aaruformat_context ctx, size_t cmp_length, size_t raw_length, uint8_t cmp_buffer, uint8_t *payload)
	Read and decompress an LZMA-compressed flux payload from the image stream.
static int32_t	validate_flux_payload_crcs (const uint8_t cmp_buffer, size_t cmp_length, const uint8_t payload, size_t raw_length, uint64_t expected_cmp_crc, uint64_t expected_raw_crc)
	Validate CRC64 checksums for a flux payload block.
static int32_t	extract_flux_data_buffers (const FluxEntry flux_entry, const uint8_t payload, size_t raw_length, uint8_t data_data, uint32_t data_length, uint8_t index_data, uint32_t index_length)
	Extract data and index buffers from decompressed payload and copy to output buffers.
int32_t	aaruf_read_flux_capture (void context, uint32_t head, uint16_t track, uint8_t subtrack, uint32_t capture_index, uint8_t index_data, uint32_t index_length, uint8_t data_data, uint32_t *data_length)
	Read a specific flux capture's data and index buffers from the image.

Variables
static const UT_icd	FLUX_CAPTURE_RECORD_ICD = {sizeof(FluxCaptureRecord), NULL, NULL, flux_capture_record_dtor}

Function Documentation

◆ aaruf_clear_flux_captures()

int32_t aaruf_clear_flux_captures ( void * context )

Clear all flux captures from the context.

This function removes all flux captures from the context, freeing all associated memory including the flux_captures utarray, flux_entries array, and the flux capture lookup map. The flux_data_header is zeroed.

This function is useful for resetting the flux capture state, particularly in write mode when starting a new image or when discarding previously added captures.

Parameters

context Pointer to an initialized aaruformat context. Must not be NULL.

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Return values

AARUF_STATUS_OK	All flux captures successfully cleared.
AARUF_ERROR_NOT_AARUFORMAT	Invalid context or context magic mismatch.

Note: This function is safe to call even if no flux captures are present (no-op).; After this call, ctx->flux_captures, ctx->flux_entries, and ctx->flux_map are all NULL/cleared, and ctx->flux_data_header is zeroed.; The function does not affect the image file itself; it only clears in-memory state. To remove flux data from an image file, the image must be rewritten.

See also: aaruf_write_flux_capture() to add flux captures; aaruf_get_flux_captures() to retrieve flux capture metadata

Definition at line 790 of file flux.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_NOT_AARUFORMAT, AARUF_STATUS_OK, FATAL, aaruformat_context::flux_captures, aaruformat_context::flux_data_header, aaruformat_context::flux_entries, flux_map_clear(), aaruformat_context::magic, and TRACE.

◆ aaruf_get_flux_captures()

int32_t aaruf_get_flux_captures	(	void *	context,
		uint8_t *	buffer,
		size_t *	length )

Retrieve metadata for all flux captures in the image.

This function retrieves metadata for all flux captures stored in the AaruFormat image. The metadata includes head, track, subtrack, captureIndex, indexResolution, and dataResolution for each capture, but does not include the actual flux data or index buffers (use aaruf_read_flux_capture() to retrieve those).

The function can be called with a NULL buffer to determine the required buffer size. In this case, the required length is written to *length and AARUF_ERROR_BUFFER_TOO_SMALL is returned.

Parameters

context	Pointer to an initialized aaruformat context opened for reading. Must not be NULL.
buffer	Pointer to a buffer to receive the FluxCaptureMeta array. May be NULL to query the required size.
length	Pointer to the size of the buffer (in bytes). On input, must contain the buffer size. On output, contains the required size (if buffer is too small) or the actual size written. Must not be NULL.

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Return values

AARUF_STATUS_OK	Metadata successfully retrieved and written to buffer.
AARUF_ERROR_NOT_AARUFORMAT	Invalid context or context magic mismatch.
AARUF_ERROR_FLUX_DATA_NOT_FOUND	Image contains no flux captures.
AARUF_ERROR_BUFFER_TOO_SMALL	Buffer is NULL or too small; *length contains the required size.

Note: The buffer must be large enough to hold ctx->flux_data_header.entries * sizeof(FluxCaptureMeta) bytes.; The returned metadata array is in the same order as the flux entries in the FluxDataBlock (on-disk order).; This function only returns metadata; use aaruf_read_flux_capture() to retrieve the actual flux data and index buffers.; Flux entries are loaded on-demand (lazy loading) the first time this function or aaruf_read_flux_capture() is called, avoiding unnecessary I/O during image opening.

See also: aaruf_read_flux_capture() to retrieve actual flux data for a specific capture; FluxCaptureMeta for the structure of each metadata entry

Definition at line 497 of file flux.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_FLUX_DATA_NOT_FOUND, AARUF_ERROR_NOT_AARUFORMAT, AARUF_STATUS_OK, FluxCaptureMeta::captureIndex, FluxEntry::captureIndex, FluxCaptureMeta::dataResolution, FluxEntry::dataResolution, ensure_flux_entries_loaded(), FluxHeader::entries, FATAL, aaruformat_context::flux_data_header, aaruformat_context::flux_entries, FluxCaptureMeta::head, FluxEntry::head, FluxCaptureMeta::indexResolution, FluxEntry::indexResolution, aaruformat_context::magic, FluxCaptureMeta::subtrack, FluxEntry::subtrack, TRACE, FluxCaptureMeta::track, and FluxEntry::track.

◆ aaruf_read_flux_capture()

int32_t aaruf_read_flux_capture	(	void *	context,
		uint32_t	head,
		uint16_t	track,
		uint8_t	subtrack,
		uint32_t	capture_index,
		uint8_t *	index_data,
		uint32_t *	index_length,
		uint8_t *	data_data,
		uint32_t *	data_length )

Read a specific flux capture's data and index buffers from the image.

This function retrieves the actual flux data and index buffers for a specific flux capture identified by its head, track, subtrack, and capture_index. The function locates the corresponding FluxEntry in the flux_entries array (using the lookup map for efficiency), converts the payloadOffset (stored divided by block alignment) to an absolute file offset using blockAlignmentShift from FluxHeader, seeks to the DataStreamPayloadBlock at the specified offset, reads and decompresses the payload, validates CRC64 checksums, and extracts the data and index buffers.

The function supports both uncompressed and LZMA-compressed payload blocks. CRC64 validation is performed on both the compressed and uncompressed data.

The function can be called with NULL data buffers to determine the required buffer sizes. In this case, the required lengths are written to *data_length and *index_length, and AARUF_ERROR_BUFFER_TOO_SMALL is returned.

Parameters

context	Pointer to an initialized aaruformat context opened for reading. Must not be NULL.
head	Head number of the flux capture to retrieve.
track	Track number of the flux capture to retrieve.
subtrack	Subtrack number of the flux capture to retrieve.
capture_index	Capture index of the flux capture to retrieve.
index_data	Pointer to a buffer to receive the index buffer. May be NULL to query the required size.
index_length	Pointer to the size of the index buffer (in bytes). On input, must contain the buffer size. On output, contains the required size (if buffer is too small) or the actual size written. Must not be NULL.
data_data	Pointer to a buffer to receive the data buffer. May be NULL to query the required size.
data_length	Pointer to the size of the data buffer (in bytes). On input, must contain the buffer size. On output, contains the required size (if buffer is too small) or the actual size written. Must not be NULL.

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Return values

AARUF_STATUS_OK	Flux capture data successfully retrieved and written to buffers.
AARUF_ERROR_NOT_AARUFORMAT	Invalid context, context magic mismatch, or invalid image stream.
AARUF_ERROR_FLUX_DATA_NOT_FOUND	No flux captures in image or specified capture not found.
AARUF_ERROR_BUFFER_TOO_SMALL	One or both buffers are NULL or too small; data_length and index_length contain required sizes.
AARUF_ERROR_CANNOT_READ_BLOCK	Failed to seek to payload or read payload header.
AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK	LZMA decompression failed or invalid compression format.
AARUF_ERROR_INVALID_BLOCK_CRC	CRC64 checksum mismatch (compressed or uncompressed).
AARUF_ERROR_INCORRECT_DATA_SIZE	Payload section length exceeds 32-bit limits.
AARUF_ERROR_NOT_ENOUGH_MEMORY	Memory allocation failed for decompression buffers.
AARUF_ERROR_UNSUPPORTED_COMPRESSION	Unsupported compression type in payload header.

Note: The function first attempts to locate the flux entry using the lookup map (O(1) lookup). If the map is not available or the entry is not found, it falls back to a linear search through flux_entries (O(n)).; The payload data is stored as [data_buffer][index_buffer] concatenated, with indexOffset indicating where the index buffer starts.; Both buffers must be large enough to hold the respective data. The function validates buffer sizes before copying data.; The caller is responsible for freeing the returned buffers if they were allocated by the caller.; CRC64 validation is performed on both compressed and uncompressed data to ensure data integrity.

See also: aaruf_get_flux_captures() to retrieve metadata for all flux captures; aaruf_write_flux_capture() to add flux captures during write mode; DataStreamPayloadHeader for the structure of payload blocks

Definition at line 1201 of file flux.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_FLUX_DATA_NOT_FOUND, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_UNSUPPORTED_COMPRESSION, AARUF_STATUS_OK, FluxHeader::blockAlignmentShift, FluxEntry::captureIndex, DataStreamPayloadHeader::cmpCrc64, DataStreamPayloadHeader::cmpLength, DataStreamPayloadHeader::compression, DataStreamPayloadHeader::crc64, ensure_flux_entries_loaded(), FluxHeader::entries, extract_flux_data_buffers(), FATAL, find_flux_entry_by_key(), aaruformat_context::flux_data_header, aaruformat_context::flux_entries, FluxEntry::head, aaruformat_context::imageStream, DataStreamPayloadHeader::length, Lzma, aaruformat_context::magic, None, FluxEntry::payloadOffset, read_flux_payload_header(), read_lzma_compressed_payload(), read_uncompressed_payload(), FluxEntry::subtrack, TRACE, FluxEntry::track, and validate_flux_payload_crcs().

◆ aaruf_write_flux_capture()

int32_t aaruf_write_flux_capture	(	void *	context,
		uint32_t	head,
		uint16_t	track,
		uint8_t	subtrack,
		uint32_t	capture_index,
		uint64_t	data_resolution,
		uint64_t	index_resolution,
		const uint8_t *	data,
		uint32_t	data_length,
		const uint8_t *	index,
		uint32_t	index_length )

Add a flux capture to the image during write mode.

This function adds a new flux capture to the image being written. The capture includes both data and index buffers, along with metadata specifying the head, track, subtrack, capture index, and resolution information for both streams.

The function copies the provided data and index buffers into internal storage (utarray) and creates a corresponding FluxEntry in the flux_entries array. The actual payload data is written to the image later during image finalization (in write_flux_blocks() and write_flux_capture_payload()).

The flux capture lookup map is updated to enable efficient retrieval of the capture by its identifier tuple.

Parameters

context	Pointer to an initialized aaruformat context opened for writing. Must not be NULL.
head	Head number the flux capture corresponds to.
track	Track number the flux capture corresponds to.
subtrack	Subtrack number the flux capture corresponds to.
capture_index	Capture index, allowing multiple captures for the same location.
data_resolution	Resolution in picoseconds for the data stream.
index_resolution	Resolution in picoseconds for the index stream.
data	Pointer to the flux data buffer. May be NULL if data_length is 0.
data_length	Length of the data buffer in bytes.
index	Pointer to the flux index buffer. May be NULL if index_length is 0.
index_length	Length of the index buffer in bytes.

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Return values

AARUF_STATUS_OK	Flux capture successfully added to the context.
AARUF_ERROR_NOT_AARUFORMAT	Invalid context or context magic mismatch.
AARUF_READ_ONLY	Context is not in write mode.
AARUF_ERROR_INCORRECT_DATA_SIZE	Invalid buffer pointers or combined size exceeds UINT32_MAX.
AARUF_ERROR_NOT_ENOUGH_MEMORY	Memory allocation failed for buffers or map entry.

Note: The function copies the data and index buffers; the caller retains ownership of the original buffers and may free them after this call.; The combined size of data_length + index_length must not exceed UINT32_MAX.; The maximum number of flux captures is limited to UINT16_MAX (65535).; The payloadOffset field in the FluxEntry is set to 0 initially and is populated later when the payload block is written during image finalization.; If adding the capture to the lookup map fails, the function performs cleanup and restores the previous state.

See also: aaruf_read_flux_capture() to read flux captures from an image; aaruf_clear_flux_captures() to remove all flux captures; write_flux_blocks() for when payload blocks are written

Definition at line 616 of file flux.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, aaruf_crc64_data(), AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_NOT_ENOUGH_MEMORY, AARUF_READ_ONLY, AARUF_STATUS_OK, FluxEntry::captureIndex, FluxHeader::crc64, FluxCaptureRecord::data_buffer, FluxCaptureRecord::data_length, FluxEntry::dataResolution, aaruformat_context::dirty_flux_block, FluxHeader::entries, FluxCaptureRecord::entry, FATAL, FLUX_CAPTURE_RECORD_ICD, aaruformat_context::flux_captures, aaruformat_context::flux_data_header, aaruformat_context::flux_entries, flux_map_add(), FluxDataBlock, FluxEntry::head, FluxHeader::identifier, FluxCaptureRecord::index_buffer, FluxCaptureRecord::index_length, FluxEntry::indexOffset, FluxEntry::indexResolution, aaruformat_context::is_writing, aaruformat_context::magic, FluxEntry::payloadOffset, FluxEntry::subtrack, TRACE, and FluxEntry::track.

◆ ensure_flux_entries_loaded()

int32_t ensure_flux_entries_loaded ( aaruformat_context * ctx )

static

Lazy load flux data block if not already loaded.

This helper function checks if flux entries are loaded, and if not, finds the FluxDataBlock in the index and loads it. This enables lazy loading of flux entries only when they are actually needed.

Parameters

ctx	Pointer to the aaruformat context. Must not be NULL.

Returns: AARUF_STATUS_OK if flux entries are loaded (or no flux data exists), or an error code on failure.

Definition at line 415 of file flux.c.

References AARUF_ERROR_FLUX_DATA_NOT_FOUND, AARUF_STATUS_OK, IndexEntry::blockType, FluxHeader::entries, aaruformat_context::flux_data_header, aaruformat_context::flux_entries, FluxDataBlock, aaruformat_context::index_entries, and process_flux_data_block().

Referenced by aaruf_get_flux_captures(), and aaruf_read_flux_capture().

◆ extract_flux_data_buffers()

int32_t extract_flux_data_buffers	(	const FluxEntry *	flux_entry,
		const uint8_t *	payload,
		size_t	raw_length,
		uint8_t *	data_data,
		uint32_t *	data_length,
		uint8_t *	index_data,
		uint32_t *	index_length )

static

Extract data and index buffers from decompressed payload and copy to output buffers.

Parameters

flux_entry	Pointer to the flux entry containing index offset information. Must not be NULL.
payload	Pointer to the decompressed payload buffer. Can be NULL if raw_length is 0.
raw_length	Length of the decompressed payload.
data_data	Output buffer for data portion. Can be NULL for size query.
data_length	Input/output parameter for data buffer size/required size. Must not be NULL.
index_data	Output buffer for index portion. Can be NULL for size query.
index_length	Input/output parameter for index buffer size/required size. Must not be NULL.

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Definition at line 1088 of file flux.c.

References AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_INVALID_BLOCK_CRC, AARUF_STATUS_OK, FATAL, FluxEntry::indexOffset, and TRACE.

Referenced by aaruf_read_flux_capture().

◆ find_flux_entry_by_key()

const FluxEntry * find_flux_entry_by_key	(	const aaruformat_context *	ctx,
		const FluxCaptureKey *	key )

static

Find a flux entry by its identifier key.

Parameters

ctx	Pointer to the aaruformat context containing flux data. Must not be NULL.
key	Pointer to the FluxCaptureKey identifying the flux capture. Must not be NULL.

Returns: Pointer to the matching FluxEntry, or NULL if not found.

Definition at line 833 of file flux.c.

References FluxCaptureKey::captureIndex, FluxEntry::captureIndex, FluxHeader::entries, aaruformat_context::flux_data_header, aaruformat_context::flux_entries, aaruformat_context::flux_map, FluxCaptureKey::head, FluxEntry::head, FluxCaptureMapEntry::index, FluxCaptureKey::subtrack, FluxEntry::subtrack, FluxCaptureKey::track, and FluxEntry::track.

Referenced by aaruf_read_flux_capture().

◆ flux_capture_record_dtor()

void flux_capture_record_dtor ( void * element )

static

Destructor callback for FluxCaptureRecord elements in a utarray.

This function is used by the utarray library to clean up dynamically allocated memory when a FluxCaptureRecord is removed from or when the array is freed. It safely frees both the data_buffer and index_buffer fields if they are non-NULL, and then nullifies the pointers to prevent double-free errors.

Parameters

element Pointer to the FluxCaptureRecord element to destroy. May be NULL.

Note: This function is registered with utarray via FLUX_CAPTURE_RECORD_ICD and is called automatically by utarray_free() and utarray_erase() operations.

Definition at line 54 of file flux.c.

References FluxCaptureRecord::data_buffer, and FluxCaptureRecord::index_buffer.

◆ flux_map_add()

int flux_map_add	(	aaruformat_context *	ctx,
		const FluxCaptureKey *	key,
		uint32_t	index )

static

Add or update a flux capture entry in the lookup map.

This function adds a new entry to the UTHASH-based flux capture lookup map, or updates an existing entry if a matching key is already present. The map enables O(1) lookup of flux captures by their (head, track, subtrack, captureIndex) identifier tuple.

If an entry with the same key already exists, its index is updated to the new value. If no entry exists, a new FluxCaptureMapEntry is allocated and added to the map.

Parameters

ctx	Pointer to the aaruformat context containing the flux_map. Must not be NULL.
key	Pointer to the FluxCaptureKey identifying the flux capture (head, track, subtrack, captureIndex). Must not be NULL.
index	The array index in ctx->flux_entries that corresponds to this flux capture.

Returns: 0 on success, -1 on memory allocation failure.

Note: On allocation failure, the function returns -1 and the map remains unchanged.; This function is used internally during map rebuilding and when adding new flux captures in write mode.

Definition at line 122 of file flux.c.

References aaruformat_context::flux_map, FluxCaptureMapEntry::index, and FluxCaptureMapEntry::key.

Referenced by aaruf_write_flux_capture(), and flux_map_rebuild_from_entries().

◆ flux_map_clear()

void flux_map_clear ( aaruformat_context * ctx )

static

Clear and deallocate the flux capture lookup map.

This function iterates through all entries in the UTHASH-based flux capture lookup map, removes each entry from the hash table, frees its memory, and sets the map pointer to NULL. This is used during cleanup operations and when rebuilding the map from scratch.

The function is safe to call even if the map is already NULL or empty.

Parameters

ctx	Pointer to the aaruformat context containing the flux_map to clear. Must not be NULL.

Note: This function does not free the flux_entries array or flux_captures utarray; it only clears the hash table used for O(1) lookup of flux captures.

Definition at line 84 of file flux.c.

References aaruformat_context::flux_map.

Referenced by aaruf_clear_flux_captures(), flux_map_rebuild_from_entries(), and process_flux_data_block().

◆ flux_map_rebuild_from_entries()

int32_t flux_map_rebuild_from_entries ( aaruformat_context * ctx )

Rebuild the flux capture lookup map from the flux_entries array.

This function clears any existing flux capture lookup map and rebuilds it from the ctx->flux_entries array. The map provides O(1) lookup of flux captures by their (head, track, subtrack, captureIndex) identifier tuple, which is used by aaruf_read_flux_capture() and other flux access functions.

The function iterates through all entries in ctx->flux_entries and adds each one to the hash table, mapping its identifier to its array index. If any entry fails to be added (due to memory allocation failure), the entire map is cleared and an error is returned.

Parameters

ctx	Pointer to the aaruformat context containing flux_entries and flux_map. Must not be NULL.

Returns: AARUF_STATUS_OK on success, or AARUF_ERROR_NOT_ENOUGH_MEMORY if memory allocation fails during map construction.

Return values

AARUF_STATUS_OK	The map was successfully rebuilt (or no entries to process).
AARUF_ERROR_NOT_ENOUGH_MEMORY	Memory allocation failed; the map is cleared.

Note: If ctx->flux_entries is NULL or ctx->flux_data_header.entries is 0, the function clears the map and returns AARUF_STATUS_OK (no-op).; On failure, the map is cleared to ensure a consistent state.; This function is called automatically by process_flux_data_block() after successfully reading flux entries from the image.

See also: flux_map_clear() for clearing the map; flux_map_add() for adding individual entries; process_flux_data_block() for when this is called during image opening

Definition at line 171 of file flux.c.

References AARUF_ERROR_NOT_ENOUGH_MEMORY, AARUF_STATUS_OK, FluxEntry::captureIndex, FluxHeader::entries, FATAL, aaruformat_context::flux_data_header, aaruformat_context::flux_entries, flux_map_add(), flux_map_clear(), FluxEntry::head, FluxEntry::subtrack, and FluxEntry::track.

Referenced by process_flux_data_block(), and write_flux_blocks().

◆ process_flux_data_block()

void process_flux_data_block	(	aaruformat_context *	ctx,
		const IndexEntry *	entry )

Parse and integrate a Flux Data block from the image stream into the context.

This function seeks to the byte offset specified by the supplied entry, reads a FluxHeader followed by the declared number of FluxEntry records, validates the block through its CRC64, rebuilds the flux capture lookup map, and populates multiple fields in the provided ctx:

ctx->flux_data_header (identifier, entries, crc64)
ctx->flux_entries (raw array with ALL flux entries in on-disk order)
ctx->flux_capture_map (hash table mapping (head, track, subtrack, captureIndex) to entry indices)
ctx->imageInfo.ImageSize (incremented by sizeof(FluxEntry) * entries)

Before reading new data, the function performs cleanup of any existing flux-related state:

Frees and clears ctx->flux_captures if it exists (write-mode remnants)
Frees and clears ctx->flux_entries if it exists (from previous calls or partial reads)
Clears ctx->flux_capture_map (via flux_map_clear())
Zeros ctx->flux_data_header

After successfully reading and validating the flux entries, the function rebuilds the in-memory flux capture lookup map by calling flux_map_rebuild_from_entries(). This map enables O(1) lookup of flux captures by their identifiers (head, track, subtrack, captureIndex), which is used by aaruf_read_flux_capture() and other flux access functions.

The function is intended for internal library use and is NOT part of the stable public API (no versioning guarantees). It is called on-demand (lazy loading) when flux data is first accessed, rather than during image opening, to avoid unnecessary I/O if flux data is never used.

Processing Flow:

Validation: Check ctx and ctx->imageStream are valid
Cleanup: Free existing flux_captures, flux_entries, and clear flux_capture_map
Seek: Seek to entry->offset in the image stream
Read Header: Read FluxHeader structure
Validate Identifier: Verify identifier == FluxDataBlock
Allocate Entries: Allocate memory for flux_entries array
Read Entries: Read all FluxEntry structures from the stream
Validate CRC64: Compute and verify CRC64 checksum over entries
Rebuild Map: Call flux_map_rebuild_from_entries() to build lookup map
Update ImageSize: Increment ctx->image_info.ImageSize

Error & early-return behavior (no exception mechanism, all via logging + early return):

NULL ctx or NULL ctx->imageStream: Logs FATAL and returns immediately; context left untouched.
Seek failure: FATAL + return; context left untouched (cleanup already performed).
FluxHeader read short: flux_data_header zeroed, TRACE logged, return.
Identifier mismatch: flux_data_header zeroed, TRACE logged, return.
Allocation failure for flux_entries: flux_data_header zeroed, FATAL logged, return.
Short read of FluxEntry array: flux_data_header zeroed, allocated flux_entries freed, FATAL logged, return.
CRC mismatch: TRACE logged and return; (NOTE: at this point flux_entries remain allocated and flux_data_header retains the just-read values, but the lookup map is not built, so entries are not accessible via lookup functions. Caller may wish to discard them or trigger re-read.)
Map rebuild failure: flux_entries freed, flux_data_header zeroed, FATAL logged, return.

Memory management:

Frees any pre-existing ctx->flux_captures (utarray) before processing
Frees any pre-existing ctx->flux_entries before allocating new ones
Allocates ctx->flux_entries with malloc() sized to entries * sizeof(FluxEntry)
On certain failure paths (short reads, map rebuild failure) allocated memory is freed
On CRC mismatch, allocated memory is kept but map is not built (entries not accessible via lookup)
The function is idempotent in terms of memory: it cleans up before processing, so repeated calls will not leak memory. However, the function is expected to be called exactly once per context lifetime during image opening.

Flux Capture Lookup Map: After successfully reading and validating flux entries, the function rebuilds the in-memory hash table (ctx->flux_capture_map) that maps flux capture identifiers to array indices. This enables efficient lookup of flux captures by their (head, track, subtrack, captureIndex) tuple. The map is built using UTHASH and is used by aaruf_read_flux_capture() and other flux access functions. If map rebuild fails, the function cleans up all allocated resources and returns.

Thread safety:

Not thread-safe: mutates shared state in ctx without synchronization.
Must not be called concurrently with readers/writers referencing the same context.

Preconditions (

Precondition

):

ctx != NULL

ctx->imageStream is a valid FILE* opened for reading at least up to the block region.

entry != NULL and entry->offset points to the start of a well-formed Flux Data block.

Postconditions (
Postcondition
) on success (CRC valid and map rebuilt):

ctx->flux_data_header.identifier == FluxDataBlock

ctx->flux_data_header.entries > 0 implies ctx->flux_entries != NULL

ctx->flux_capture_map is populated with entries mapping identifiers to indices

ctx->imageInfo.ImageSize incremented by flux data size

ctx->flux_captures == NULL (cleared if it existed)

Limitations / Caveats:

No explicit status code: callers infer success by inspecting ctx->flux_data_header.entries and presence of ctx->flux_entries after invocation.

In case of CRC mismatch, flux_entries are retained but flux_capture_map is not built, so entries are not accessible via lookup functions. Caller may wish to discard them or trigger re-read.

The function is idempotent in terms of memory (cleans up before processing), but is expected to be called exactly once per context lifetime during image opening.

Logging strategy:

FATAL used for unrecoverable structural or resource errors (seek failure, allocation failure, map rebuild failure).

TRACE used for informational / soft failures (e.g., CRC mismatch, identifier mismatch, short read).

Parameters

ctx Mutable pointer to an aaruformatContext receiving parsed flux metadata.

entry Pointer to the index entry describing this Flux Data block (offset required; size not strictly used beyond informational logging and sequential reading).

Returns
void This function does not return a status code; errors are reported via logging side effects.

Warning
Absence of a returned status requires defensive post-call validation by the caller.

CRC mismatch leaves possibly invalid data in ctx->flux_entries, and the lookup map is not built, making entries inaccessible via lookup functions.

Map rebuild failure results in complete cleanup of flux-related state, leaving the context without flux data even if the entries were successfully read and validated.

See also
flux_map_rebuild_from_entries() for the map rebuilding logic

flux_map_clear() for the map clearing logic

aaruf_read_flux_capture() for using the lookup map to access flux captures

Definition at line 307 of file flux.c.

References aaruf_crc64_data(), AARUF_STATUS_OK, FluxHeader::crc64, FluxHeader::entries, FATAL, aaruformat_context::flux_captures, aaruformat_context::flux_data_header, aaruformat_context::flux_entries, flux_map_clear(), flux_map_rebuild_from_entries(), FluxDataBlock, FluxHeader::identifier, aaruformat_context::image_info, ImageInfo::ImageSize, aaruformat_context::imageStream, IndexEntry::offset, and TRACE.

Referenced by ensure_flux_entries_loaded().

◆ read_flux_payload_header()

int32_t read_flux_payload_header	(	const aaruformat_context *	ctx,
		uint64_t	payload_offset,
		DataStreamPayloadHeader *	header )

static

Read and validate a flux payload block header from the image stream.

Parameters

ctx	Pointer to the aaruformat context. Must not be NULL.
payload_offset	File offset where the payload block starts.
header	Output parameter for the read header. Must not be NULL.

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Definition at line 865 of file flux.c.

References AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_STATUS_OK, DataStreamPayloadBlock, DataStreamPayloadHeader::dataType, FATAL, FluxData, DataStreamPayloadHeader::identifier, aaruformat_context::imageStream, and TRACE.

Referenced by aaruf_read_flux_capture().

◆ read_lzma_compressed_payload()

int32_t read_lzma_compressed_payload	(	const aaruformat_context *	ctx,
		size_t	cmp_length,
		size_t	raw_length,
		uint8_t **	cmp_buffer,
		uint8_t **	payload )

static

Read and decompress an LZMA-compressed flux payload from the image stream.

Parameters

ctx	Pointer to the aaruformat context. Must not be NULL.
cmp_length	Compressed length including LZMA properties.
raw_length	Expected uncompressed length.
cmp_buffer	Output parameter for compressed buffer pointer (caller must free). Can be NULL if allocation fails.
payload	Output parameter for decompressed payload buffer pointer (caller must free). Can be NULL if allocation fails.

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Definition at line 971 of file flux.c.

References AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK, AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_ERROR_NOT_ENOUGH_MEMORY, aaruf_lzma_decode_buffer(), AARUF_STATUS_OK, FATAL, aaruformat_context::imageStream, LZMA_PROPERTIES_LENGTH, and TRACE.

Referenced by aaruf_read_flux_capture().

◆ read_uncompressed_payload()

int32_t read_uncompressed_payload	(	const aaruformat_context *	ctx,
		size_t	cmp_length,
		size_t	raw_length,
		uint8_t **	cmp_buffer,
		uint8_t **	payload )

static

Read an uncompressed flux payload from the image stream.

Parameters

ctx	Pointer to the aaruformat context. Must not be NULL.
cmp_length	Compressed length (should equal raw_length for uncompressed).
raw_length	Uncompressed length.
cmp_buffer	Output parameter for compressed buffer pointer (caller must free). Can be NULL if allocation fails.
payload	Output parameter for payload buffer pointer (same as cmp_buffer for uncompressed).

Returns: AARUF_STATUS_OK on success, or an error code on failure.

Definition at line 921 of file flux.c.

References AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK, AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_ERROR_NOT_ENOUGH_MEMORY, AARUF_STATUS_OK, FATAL, aaruformat_context::imageStream, and TRACE.

Referenced by aaruf_read_flux_capture().

◆ validate_flux_payload_crcs()

int32_t validate_flux_payload_crcs	(	const uint8_t *	cmp_buffer,
		size_t	cmp_length,
		const uint8_t *	payload,
		size_t	raw_length,
		uint64_t	expected_cmp_crc,
		uint64_t	expected_raw_crc )

static

Validate CRC64 checksums for a flux payload block.

Parameters

cmp_buffer	Compressed buffer to validate. Can be NULL if cmp_length is 0.
cmp_length	Compressed length.
payload	Uncompressed payload buffer to validate. Can be NULL if raw_length is 0.
raw_length	Uncompressed length.
expected_cmp_crc	Expected CRC64 of compressed data.
expected_raw_crc	Expected CRC64 of uncompressed data.

Returns: AARUF_STATUS_OK on success, or AARUF_ERROR_INVALID_BLOCK_CRC on mismatch.

Definition at line 1048 of file flux.c.

References aaruf_crc64_data(), AARUF_ERROR_INVALID_BLOCK_CRC, AARUF_STATUS_OK, FATAL, and TRACE.

Referenced by aaruf_read_flux_capture().

Variable Documentation

◆ FLUX_CAPTURE_RECORD_ICD

const UT_icd FLUX_CAPTURE_RECORD_ICD = {sizeof(FluxCaptureRecord), NULL, NULL, flux_capture_record_dtor}

static

Definition at line 65 of file flux.c.

Referenced by aaruf_write_flux_capture().

ctx	Mutable pointer to an aaruformatContext receiving parsed flux metadata.
entry	Pointer to the index entry describing this Flux Data block (offset required; size not strictly used beyond informational logging and sequential reading).

Data Structures

Functions

Variables

Function Documentation

◆ aaruf_clear_flux_captures()

◆ aaruf_get_flux_captures()

◆ aaruf_read_flux_capture()

◆ aaruf_write_flux_capture()

◆ ensure_flux_entries_loaded()

◆ extract_flux_data_buffers()

◆ find_flux_entry_by_key()

◆ flux_capture_record_dtor()

◆ flux_map_add()

◆ flux_map_clear()

◆ flux_map_rebuild_from_entries()

◆ process_flux_data_block()

◆ read_flux_payload_header()

◆ read_lzma_compressed_payload()

◆ read_uncompressed_payload()

◆ validate_flux_payload_crcs()

Variable Documentation

◆ FLUX_CAPTURE_RECORD_ICD