#include <errno.h>
#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <aaruformat.h>
#include "erasure_internal.h"
#include "internal.h"
#include "log.h"
#include "utarray.h"

Functions
static void	aaruf_set_open_error (const int error_code)
static void	cleanup_open_failure (aaruformat_context *ctx)
void *	aaruf_open (const char filepath, const bool resume_mode, const char options)
	Opens an existing AaruFormat image file.

Function Documentation

◆ aaruf_open()

void * aaruf_open	(	const char *	filepath,
		const bool	resume_mode,
		const char *	options )

Opens an existing AaruFormat image file.

Opens the specified image file and returns a pointer to the initialized aaruformat context. This function performs comprehensive validation of the image file format, reads and processes all index entries, initializes data structures for reading (and optionally writing in resume mode), and sets up caches for optimal performance. It supports multiple AaruFormat versions and handles various block types including data blocks, deduplication tables, metadata, and checksums.

Operational Modes:

Read-Only Mode (resume_mode = false):

Validates and reads existing image in read-only mode
Loads all index entries, DDT, and metadata structures
Initializes block and header caches for efficient reading
Suitable for accessing, extracting, or verifying completed AaruFormat images
File is opened in binary read mode; no modifications possible
Requires valid user data DDT to be present in the image

Resume/Write Mode (resume_mode = true):

Validates and opens an existing image for continued writing (resume operations)
Loads all existing index entries, DDT, and metadata
Prepares context for additional write operations to incomplete images
Suitable for resuming interrupted image creation or appending to images
File is opened in binary read/write mode for additional data/blocks
Requires the image to be in a valid resumable state (proper headers, valid index, DDT present)
Requires image to be in AaruFormat version 2.0 or later (version 1.x images cannot be resumed)
Options string is parsed to configure writing parameters
Checksum contexts are reinitialized based on options if checksums are present

Index and Block Processing: The function processes all indexed blocks from the image:

Data blocks: User and negative/overflow sectors with deduplication references
DDT blocks: Deduplication table entries mapping sectors to physical block locations
Geometry blocks: Cylinder-head-sector information for certain media types
Metadata blocks: CICM XML, Aaru JSON, and other format-specific metadata
Track blocks: CD/DVD track information and sector maps
Dump hardware blocks: Recording device specifications and configuration
Checksum blocks: Media tags and image-level checksums (MD5, SHA-1, SHA-256, BLAKE3, SpamSum)

Non-critical block processing errors are logged but don't prevent opening (logging only). Critical errors (especially DDT processing failures) cause the open operation to fail. Unknown block types are logged but silently ignored for forward compatibility.

Parameters

filepath	Path to the image file to open. Must be a valid readable path. When opening in resume mode (resume_mode=true), the file must also be writable. The file must contain a valid AaruFormat header and index.
resume_mode	Boolean flag controlling the operational mode: false: Open in read-only mode for accessing completed images. File is opened read-only; no modifications can be made. Suitable for extraction, analysis, and verification. Supports both AaruFormat version 1.x and 2.x images. true: Open in resume/write mode for continuing interrupted image creation. File is opened read/write for additional operations. Requires existing valid image structure. IMPORTANT: Only AaruFormat version 2.x or later images can be opened in resume mode. Version 1.x images cannot be resumed and will fail with AARUF_ERROR_INCOMPATIBLE_VERSION. Write operations are handled as if resuming an incomplete creation. Options string is parsed for write configuration.
options	String with opening/resume options in key=value format, semicolon-separated. Used primarily in resume mode to configure checksum and compression parameters. Supported options (resume mode only): "deduplicate=true\|false": Enable/disable sector deduplication (if supported in image) "md5=true\|false": Recalculate MD5 checksum during resume operations "sha1=true\|false": Recalculate SHA-1 checksum during resume operations "sha256=true\|false": Recalculate SHA-256 checksum during resume operations "spamsum=true\|false": Recalculate SpamSum fuzzy hash during resume operations "blake3=true\|false": Recalculate BLAKE3 checksum during resume operations "compress=true\|false": Use compression for new data blocks in resume operations Example: "deduplicate=true;md5=true;sha1=true" In read-only mode (resume_mode=false), this parameter is typically NULL or ignored.

Returns: Returns one of the following:

Return values

aaruformatContext*

Successfully opened and initialized context. The returned pointer contains:

Validated AaruFormat headers and metadata
Processed index entries with all discoverable blocks
Loaded deduplication tables (DDT) for efficient sector access
Initialized block and header caches for performance
Open file stream (read-only or read/write depending on mode)
Populated image information and geometry data
ECC context initialized for error correction support
In resume mode: Write context and checksum contexts initialized from options

NULL

Opening failed. The specific error can be determined by checking errno, which will be set to:

AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) when memory allocation fails for:
- Context allocation
- Readable sector tags bitmap allocation
- Application version string allocation
- Image version string allocation
- Index entries array allocation
- DDT processing structures
AARUF_ERROR_FILE_TOO_SMALL (-2) when file reading fails:
- Cannot read the AaruFormat header (file too small or corrupted)
- Cannot read the extended header for version 2+ formats
- Cannot seek to or read the index block
AARUF_ERROR_NOT_AARUFORMAT (-1) when format validation fails:
- File identifier doesn't match DIC_MAGIC or AARU_MAGIC
- File is not a valid AaruFormat image
AARUF_ERROR_INCOMPATIBLE_VERSION (-3) when:
- Image major version exceeds the maximum supported version
- Future format versions that cannot be read by this library
- Version 1.x images are opened in resume mode (only version 2.x+ can be resumed)
- Other version incompatibility issues with resume mode requirements
AARUF_ERROR_CANNOT_READ_INDEX (-4) when index processing fails:
- Cannot seek to the index offset specified in the header
- Cannot read the index signature
- Index signature is not a recognized index block type
- Index processing functions return NULL (corrupted index)
Other error codes may be propagated from block processing functions:
- Data block processing errors
- DDT processing errors (critical failure)
- Metadata processing errors (non-critical, logging only)
- File I/O errors in resume mode

Note

Format Support:

Supports AaruFormat versions 1.x and 2.x
Automatically detects and handles different index formats (v1, v2, v3)
Backwards compatible with older DIC format identifiers
Handles both small and large deduplication tables
Supports optional user data DDT, necessary for sector access

Block Processing:

Processes all indexed blocks including data, DDT, geometry, metadata, tracks, CICM, dump hardware, and checksums
Non-critical block processing errors are logged but don't prevent opening
Critical errors (DDT processing failures) cause opening to fail
Unknown block types are logged but ignored for future compatibility
Block processing is the same in both read-only and resume modes

Memory Management:

Allocates memory for various context structures and caches
On failure, all previously allocated memory is properly cleaned up
The returned context must be freed using aaruf_close()
In resume mode, additional write buffers may be allocated based on options

Performance Optimization:

Initializes block and header caches based on sector size and available memory
Cache sizes are calculated to optimize memory usage and access patterns
ECC context is pre-initialized for Compact Disc support
Cache strategies may differ between read-only and resume modes

Resume Mode Considerations:

Image must be in a valid state for resume operations
Image MUST be in AaruFormat version 2.0 or later (version 1.x images cannot be resumed)
Opening a version 1.x image with resume_mode=true will fail immediately with AARUF_ERROR_INCOMPATIBLE_VERSION
Partial or corrupted images may fail to open in resume mode
Options are parsed to reconfigure checksums and compression if needed
Write position is calculated based on existing data and index entries
Deduplication hash maps are reconstructed from existing DDT entries
Some checksums (MD5, SHA-1, SHA-256) may need to be recalculated from scratch if resuming

Warning

The function requires a valid user data deduplication table to be present. Images without a DDT will fail to open even if otherwise valid.

File access permissions must be appropriate for the selected mode:

Read-only mode: File must be readable
Resume mode: File must be readable AND writable The file must not be locked by other processes in resume mode.

Resume mode has additional validation requirements:

Image must not be finalized (index must not be marked as complete)
Image MUST be AaruFormat version 2.x or later (version 1.x images are not supported in resume mode)
Image must have a valid, reconstructible DDT
File I/O errors in resume mode may leave the image in an inconsistent state

Some memory allocations (version strings, checksum contexts) are optional. Failure in optional allocations doesn't prevent opening but may affect functionality that depends on checksums or version information.

See also: aaruf_close() for proper context cleanup and image finalization; aaruf_read_sector() for reading sectors from opened images; aaruf_write_sector() for writing sectors in resume mode; aaruf_identify() for identifying image type before opening

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

Definition at line 236 of file open.c.