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)
	Opens an existing AaruFormat image file.

Function Documentation

aaruf_open()

void * aaruf_open

(

const char *

filepath

)

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 operations, 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.

Parameters

filepath

Path to the image file to open.

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 ready for reading operations Populated image information and geometry data ECC context initialized for error correction support

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 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 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 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 Metadata processing errors

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

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

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()

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

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 is performed in binary read mode. The file must be accessible and not locked by other processes.

Some memory allocations (version strings) are optional and failure doesn't prevent opening, but may affect functionality that depends on version information.

< 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 125 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_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, BlockMedia, IndexEntry::blockType, CacheHeader::cache, ChecksumBlock, CicmBlock, cleanup_open_failure(), ImageInfo::CreationTime, AaruHeaderV2::creationTime, aaruformat_context::cylinders, DataBlock, IndexEntry::dataType, DeDuplicationTable, DeDuplicationTable2, DIC_MAGIC, DumpHardwareBlock, aaruformat_context::ecc_cd_context, FATAL, aaruformat_context::geometry_block, GeometryBlock, aaruformat_context::header, aaruformat_context::heads, AaruHeaderV2::identifier, GeometryBlockHeader::identifier, aaruformat_context::image_info, AaruHeaderV2::imageMajorVersion, AaruHeaderV2::imageMinorVersion, ImageInfo::ImageSize, aaruformat_context::imageStream, IndexBlock, IndexBlock2, IndexBlock3, AaruHeaderV2::indexOffset, ImageInfo::LastModificationTime, AaruHeaderV2::lastWrittenTime, LIBAARUFORMAT_MAJOR_VERSION, LIBAARUFORMAT_MINOR_VERSION, aaruformat_context::library_major_version, aaruformat_context::library_minor_version, aaruformat_context::magic, MAX_CACHE_SIZE, CacheHeader::max_items, MaxSectorTag, ImageInfo::MediaType, AaruHeaderV2::mediaType, MetadataBlock, ImageInfo::MetadataMediaType, IndexEntry::offset, 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, ImageInfo::Sectors, aaruformat_context::sectors_per_track, ImageInfo::SectorSize, aaruformat_context::shift, TapeFileBlock, TapePartitionBlock, TRACE, TracksBlock, 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().