libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
open.c File Reference
`#include <errno.h>`
`#include <inttypes.h>`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <aaruformat.h>`
`#include "internal.h"`
`#include "log.h"`
`#include "utarray.h"`

Go to the source code of this file.

## Functions
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).

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

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

Definition at line 223 of file open.c.

References AARU_CALL, AARU_EXPORT, AARU_HEADER_APP_NAME_LEN, AARU_MAGIC, aaruf_close(), aaruf_ecc_cd_init(), AARUF_ERROR_CANNOT_CREATE_FILE, AARUF_ERROR_CANNOT_READ_INDEX, AARUF_ERROR_FILE_TOO_SMALL, AARUF_ERROR_INCOMPATIBLE_VERSION, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_NOT_ENOUGH_MEMORY, aaruf_get_xml_mediatype(), AARUF_STATUS_OK, AARUF_VERSION, AARUF_VERSION_V2, AaruMetadataJsonBlock, ImageInfo::Application, AaruHeaderV2::application, AaruHeaderV2::applicationMajorVersion, AaruHeaderV2::applicationMinorVersion, ImageInfo::ApplicationVersion, aaruformat_context::block_cache, aaruformat_context::block_header_cache, DdtHeader2::blockAlignmentShift, BlockMedia, DdtHeader2::blocks, IndexEntry::blockType, CacheHeader::cache, ChecksumBlock, CicmBlock, cleanup_open_failure(), aaru_options::compress, aaruformat_context::compression_enabled, create_map(), ImageInfo::CreationTime, AaruHeaderV2::creationTime, aaruformat_context::cylinders, DataBlock, IndexEntry::dataType, aaru_options::deduplicate, aaruformat_context::deduplicate, DeDuplicationTable, DeDuplicationTable2, DIC_MAGIC, aaru_options::dictionary, DumpHardwareBlock, aaruformat_context::ecc_cd_context, FATAL, aaruformat_context::geometry_block, GeometryBlock, get_filetime_uint64(), aaruformat_context::header, aaruformat_context::heads, AaruHeaderV2::identifier, GeometryBlockHeader::identifier, aaruformat_context::image_info, AaruHeaderV2::imageMajorVersion, AaruHeaderV2::imageMinorVersion, ImageInfo::ImageSize, aaruformat_context::imageStream, aaruformat_context::index_entries, IndexBlock, IndexBlock2, IndexBlock3, AaruHeaderV2::indexOffset, aaruformat_context::is_writing, ImageInfo::LastModificationTime, AaruHeaderV2::lastWrittenTime, LIBAARUFORMAT_MAJOR_VERSION, LIBAARUFORMAT_MINOR_VERSION, aaruformat_context::library_major_version, aaruformat_context::library_minor_version, aaruformat_context::lzma_dict_size, aaruformat_context::magic, MAX_CACHE_SIZE, CacheHeader::max_items, MaxSectorTag, ImageInfo::MediaType, AaruHeaderV2::mediaType, MetadataBlock, ImageInfo::MetadataMediaType, aaruformat_context::next_block_position, IndexEntry::offset, parse_options(), process_aaru_metadata_json_block(), process_checksum_block(), process_cicm_block(), process_data_block(), process_ddt_v1(), process_ddt_v2(), process_dumphw_block(), process_geometry_block(), process_index_v1(), process_index_v2(), process_index_v3(), process_metadata_block(), process_tape_files_block(), process_tape_partitions_block(), process_tracks_block(), aaruformat_context::readableSectorTags, aaruformat_context::rewinded, aaruformat_context::sector_hash_map, ImageInfo::Sectors, aaruformat_context::sectors_per_track, ImageInfo::SectorSize, aaruformat_context::shift, TapeFileBlock, TapePartitionBlock, TRACE, TracksBlock, aaruformat_context::user_data_ddt_header, and ImageInfo::Version.

## ◆ cleanup_open_failure()

void cleanup_open_failure | ( | aaruformat_context * | ctx | ) |
| static

Definition at line 31 of file open.c.

References aaruformat_context::imageStream, and aaruformat_context::readableSectorTags.

Referenced by aaruf_open().