libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
read.c File Reference
`#include <stdlib.h>`
`#include <string.h>`
`#include <aaruformat.h>`
`#include "internal.h"`
`#include "log.h"`

Go to the source code of this file.

## Functions
int32_t | aaruf_read_media_tag (void *context, uint8_t *data, const int32_t tag, uint32_t *length)
| Reads a media tag from the AaruFormat image.
int32_t | aaruf_read_sector (void *context, const uint64_t sector_address, bool negative, uint8_t *data, uint32_t *length, uint8_t *sector_status)
| Reads a sector from the AaruFormat image.
int32_t | aaruf_read_track_sector (void *context, uint8_t *data, const uint64_t sector_address, uint32_t *length, const uint8_t track, uint8_t *sector_status)
| Reads a sector from a specific track in the AaruFormat image.
int32_t | aaruf_read_sector_long (void *context, const uint64_t sector_address, bool negative, uint8_t *data, uint32_t *length, uint8_t *sector_status)
| Reads a complete sector with all metadata from the AaruFormat image.
int32_t | aaruf_read_sector_tag (const void *context, const uint64_t sector_address, const bool negative, uint8_t *buffer, uint32_t *length, const int32_t tag)
| Reads a specific sector tag from the AaruFormat image.

## Function Documentation

## ◆ aaruf_read_media_tag()

int32_t aaruf_read_media_tag | ( | void * | context,
|  | uint8_t * | data,
|  | const int32_t | tag,
|  | uint32_t * | length )

Reads a media tag from the AaruFormat image.

Reads the specified media tag from the image and stores it in the provided buffer. Media tags contain metadata information about the storage medium such as disc information, lead-in/lead-out data, manufacturer-specific information, or other medium-specific metadata. This function uses a hash table lookup for efficient tag retrieval and supports buffer size querying when data pointer is NULL.

Parameters

  context | Pointer to the aaruformat context.
  data | Pointer to the buffer to store the tag data. Can be NULL to query tag length.
  tag | Tag identifier to read (specific to media type and format).
  length | Pointer to the length of the buffer on input; updated with actual tag length on output.

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully read the media tag. This is returned when: The context is valid and properly initialized The requested media tag exists in the image's media tag hash table The provided buffer is large enough to contain the tag data The tag data is successfully copied to the output buffer The length parameter is updated with the actual tag data length
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type)
  AARUF_ERROR_MEDIA_TAG_NOT_PRESENT | (-11) The requested media tag does not exist. This occurs when: The tag identifier is not found in the image's media tag hash table The image was created without the requested metadata The tag identifier is not supported for this media type The length parameter is set to 0 when this error is returned
  AARUF_ERROR_BUFFER_TOO_SMALL | (-10) The provided buffer is insufficient. This occurs when: The data parameter is NULL (used for length querying) The buffer length (*length) is smaller than the required tag data length The length parameter is updated with the required size for retry

Note
  Buffer Size Querying:
  - Pass data as NULL to query the required buffer size without reading data
  - The length parameter will be updated with the required size
  - This allows proper buffer allocation before the actual read operation
  Media Tag Types:
  - Tags are media-type specific (optical disc, floppy disk, hard disk, etc.)
  - Common tags include TOC data, lead-in/out, manufacturer data, defect lists
  - Tag availability depends on what was preserved during the imaging process
  Hash Table Lookup:
  - Uses efficient O(1) hash table lookup for tag retrieval
  - Tag identifiers are integer values specific to the media format
  - Hash table is populated during image opening from indexed metadata blocks

Warning
  The function performs a direct memory copy operation. Ensure the output buffer has sufficient space to prevent buffer overflows.
  Media tag data is stored as-is from the original medium. No format conversion or validation is performed on the tag content.

Definition at line 85 of file read.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_MEDIA_TAG_NOT_PRESENT, AARUF_ERROR_NOT_AARUFORMAT, AARUF_STATUS_OK, mediaTagEntry::data, FATAL, mediaTagEntry::length, aaruformat_context::magic, aaruformat_context::mediaTags, and TRACE.

## ◆ aaruf_read_sector()

int32_t aaruf_read_sector | ( | void * | context,
|  | const uint64_t | sector_address,
|  | bool | negative,
|  | uint8_t * | data,
|  | uint32_t * | length,
|  | uint8_t * | sector_status )

Reads a sector from the AaruFormat image.

Reads user data from the specified sector address in the image. This function reads only the user data portion of the sector, without any additional metadata or ECC/EDC information. It handles block-based deduplication, compression (LZMA/FLAC), and caching for optimal performance. The function supports both DDT v1 and v2 formats for sector-to-block mapping.

Parameters

  context | Pointer to the aaruformat context.
  sector_address | The logical sector address to read from.
  negative | Indicates if the sector address is negative.
  data | Pointer to buffer where sector data will be stored. Can be NULL to query length.
  length | Pointer to variable containing buffer size on input, actual data length on output.
  sector_status | Pointer to variable that will receive the sector status flags. Must not be NULL. The status indicates the condition of the sector data, such as whether it contains errors, was not dumped, or has other quality indicators from the imaging process.

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully read the sector data. This is returned when: The sector data is successfully retrieved from cache or decompressed from storage Block header and data are successfully read and processed Decompression (if needed) completes successfully The sector data is copied to the output buffer The length parameter is updated with the actual sector size
  AARUF_STATUS_SECTOR_NOT_DUMPED | (1) The sector was not dumped during imaging. This occurs when: The DDT entry indicates the sector status is SectorStatusNotDumped The original imaging process skipped this sector due to read errors The length parameter is set to the expected sector size for buffer allocation
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type)
  AARUF_ERROR_SECTOR_OUT_OF_BOUNDS | (-8) The sector address exceeds image bounds. This occurs when: sector_address is greater than or equal to ctx->imageInfo.Sectors Attempting to read beyond the logical extent of the imaged medium
  AARUF_ERROR_BUFFER_TOO_SMALL | (-10) The provided buffer is insufficient. This occurs when: The data parameter is NULL (used for length querying) The buffer length (*length) is smaller than the block's sector size The length parameter is updated with the required size for retry
  AARUF_ERROR_NOT_ENOUGH_MEMORY | (-9) Memory allocation failed. This occurs when: Cannot allocate memory for block header (if not cached) Cannot allocate memory for uncompressed block data Cannot allocate memory for compressed data buffer (LZMA/FLAC) Cannot allocate memory for decompressed block buffer
  AARUF_ERROR_CANNOT_READ_HEADER | (-6) Block header reading failed. This occurs when: Cannot read the complete BlockHeader structure from the image stream File I/O errors prevent reading header data at the calculated block offset Image file corruption or truncation
  AARUF_ERROR_CANNOT_READ_BLOCK | (-7) Block data reading failed. This occurs when: Cannot read uncompressed block data from the image stream Cannot read LZMA properties from compressed blocks Cannot read compressed data from LZMA or FLAC blocks File I/O errors during block data access
  AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK | (-17) Decompression failed. This occurs when: LZMA decoder returns a non-zero error code during decompression FLAC decoder fails to decompress audio data properly Decompressed data size doesn't match the expected block length Compression algorithm encounters corrupted or invalid compressed data
  AARUF_ERROR_UNSUPPORTED_COMPRESSION | (-13) Unsupported compression algorithm. This occurs when: The block header specifies a compression type not supported by this library Future compression algorithms not implemented in this version
  Other | error codes may be propagated from DDT decoding functions: From decode_ddt_entry_v1(): AARUF_ERROR_NOT_AARUFORMAT (-1) From decode_ddt_entry_v2(): AARUF_ERROR_NOT_AARUFORMAT (-1), AARUF_ERROR_CANNOT_READ_BLOCK (-7), AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17), AARUF_ERROR_INVALID_BLOCK_CRC (-18)

Note
  DDT Processing:
  - Automatically selects DDT v1 or v2 decoding based on ctx->ddtVersion
  - DDT decoding provides sector offset within block and block file offset
  - Handles deduplication where multiple sectors may reference the same block
  Caching Mechanism:
  - Block headers are cached for performance (ctx->blockHeaderCache)
  - Decompressed block data is cached to avoid repeated decompression (ctx->blockCache)
  - Cache hits eliminate file I/O and decompression overhead
  - Cache sizes are determined during context initialization
  Compression Support:
  - None: Direct reading of uncompressed block data
  - LZMA: Industry-standard compression with properties header
  - FLAC: Audio-optimized compression for CD audio blocks
  - Each compression type has specific decompression requirements and error conditions
  Buffer Size Querying:
  - Pass data as NULL to query the required buffer size without reading data
  - The length parameter will be updated with the block's sector size
  - Useful for dynamic buffer allocation before the actual read operation

Warning
  This function reads only user data. For complete sector data including metadata and ECC/EDC information, use aaruf_read_sector_long().
  Memory allocated for caching is managed by the context. Do not free cached block data as it may be reused by subsequent operations.
  Sector addresses are zero-based. The maximum valid address is ctx->imageInfo.Sectors - 1.

Definition at line 253 of file read.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK, AARUF_ERROR_CANNOT_READ_BLOCK, AARUF_ERROR_CANNOT_READ_HEADER, AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_NOT_ENOUGH_MEMORY, AARUF_ERROR_SECTOR_OUT_OF_BOUNDS, AARUF_ERROR_UNSUPPORTED_COMPRESSION, aaruf_flac_decode_redbook_buffer(), aaruf_lzma_decode_buffer(), AARUF_STATUS_OK, AARUF_STATUS_SECTOR_NOT_DUMPED, add_to_cache_uint64(), aaruformat_context::block_cache, aaruformat_context::block_header_cache, BlockHeader::cmpLength, BlockHeader::compression, aaruformat_context::ddt_version, decode_ddt_entry_v1(), decode_ddt_entry_v2(), FATAL, find_in_cache_uint64(), Flac, aaruformat_context::image_info, aaruformat_context::imageStream, BlockHeader::length, Lzma, LZMA_PROPERTIES_LENGTH, aaruformat_context::magic, DdtHeader2::negative, None, DdtHeader2::overflow, ImageInfo::Sectors, ImageInfo::SectorSize, BlockHeader::sectorSize, SectorStatusNotDumped, TRACE, and aaruformat_context::user_data_ddt_header.

Referenced by aaruf_read_sector_long(), and aaruf_read_track_sector().

## ◆ aaruf_read_sector_long()

int32_t aaruf_read_sector_long | ( | void * | context,
|  | const uint64_t | sector_address,
|  | bool | negative,
|  | uint8_t * | data,
|  | uint32_t * | length,
|  | uint8_t * | sector_status )

Reads a complete sector with all metadata from the AaruFormat image.

Reads the complete sector data including user data, ECC/EDC, subchannel data, and other metadata depending on the media type. For optical discs, this returns a full 2352-byte sector with sync, header, user data, and ECC/EDC. For block media with tags, this includes both the user data and tag information. The function handles complex sector reconstruction including ECC correction and format-specific metadata assembly.

Parameters

  context | Pointer to the aaruformat context.
  sector_address | The logical sector address to read from.
  negative | Indicates if the sector address is negative.
  data | Pointer to buffer where complete sector data will be stored. Can be NULL to query length.
  length | Pointer to variable containing buffer size on input, actual data length on output.
  sector_status | Pointer to variable that will receive the sector status flags. Must not be NULL. The status indicates the condition of the sector data, such as whether it contains errors, was not dumped, or has other quality indicators from the imaging process.

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully read the complete sector with metadata. This is returned when: The sector data is successfully retrieved and reconstructed with all metadata For optical discs: sync, header, user data, and ECC/EDC are assembled into 2352 bytes For block media: user data and tags are combined according to media type ECC reconstruction (if applicable) completes successfully All required metadata (prefix/suffix, subheaders, etc.) is available and applied
  AARUF_STATUS_SECTOR_NOT_DUMPED | (1) The sector or metadata was not dumped. This can occur when: The underlying sector data was not dumped during imaging CD prefix or suffix metadata indicates NotDumped status for the sector ECC reconstruction cannot be performed due to missing correction data
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type)
  AARUF_ERROR_INCORRECT_MEDIA_TYPE | (-5) The media type doesn't support long sector reading. This occurs when: ctx->imageInfo.XmlMediaType is not OpticalDisc or BlockMedia For BlockMedia: the specific media type is not supported (not Apple, Priam, etc.) Media types that don't have extended sector formats
  AARUF_ERROR_BUFFER_TOO_SMALL | (-10) The buffer is insufficient for complete sector data. This occurs when: The data parameter is NULL (used for length querying) For optical discs: buffer length is less than 2352 bytes For block media: buffer length is less than (user data size + tag size) The length parameter is updated with the required size for retry
  AARUF_ERROR_NOT_ENOUGH_MEMORY | (-9) Memory allocation failed. This occurs when: Cannot allocate memory for bare user data during optical disc processing Cannot allocate memory for user data during block media processing Memory allocation fails in underlying aaruf_read_sector() calls
  AARUF_ERROR_TRACK_NOT_FOUND | (-12) Cannot locate the sector's track. This occurs when: For optical discs: the sector address doesn't fall within any data track boundaries No track contains the specified sector address (address not in any track.start to track.end range) The track list is empty or corrupted
  AARUF_ERROR_INVALID_TRACK_FORMAT | (-14) The track has an unsupported format. This occurs when: The track type is not recognized (not Audio, Data, CdMode1, CdMode2*, etc.) Internal track format validation fails
  AARUF_ERROR_REACHED_UNREACHABLE_CODE | (-15) Internal logic error. This occurs when: Required metadata structures (sectorPrefix, sectorSuffix, etc.) are unexpectedly NULL Control flow reaches states that should be impossible with valid image data Indicates potential image corruption or library bug
  All | error codes from aaruf_read_sector() may be propagated: AARUF_ERROR_SECTOR_OUT_OF_BOUNDS (-8) - Calculated sector address exceeds image bounds AARUF_ERROR_CANNOT_READ_HEADER (-6) - Block header cannot be read AARUF_ERROR_CANNOT_READ_BLOCK (-7) - Block data cannot be read AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17) - Decompression fails AARUF_ERROR_UNSUPPORTED_COMPRESSION (-13) - Compression algorithm not supported

Note
  Optical Disc Sector Reconstruction:
  - Creates full 2352-byte sectors from separate user data, sync, header, and ECC/EDC components
  - Supports different CD modes: Mode 1, Mode 2 Form 1, Mode 2 Form 2, Mode 2 Formless
  - Handles ECC correction using stored correction data or reconstructed ECC
  - Uses prefix/suffix DDTs to determine correction strategy for each sector
  Block Media Tag Assembly:
  - Combines user data (typically 512 bytes) with media-specific tags
  - Tag sizes vary by media type: Apple (12-20 bytes), Priam (24 bytes)
  - Tags contain manufacturer-specific information like spare sector mapping
  ECC Reconstruction Modes:
  - Correct: Reconstructs ECC/EDC from user data (no stored correction data needed)
  - NotDumped: Indicates the metadata portion was not successfully read during imaging
  - Stored: Uses pre-computed correction data stored separately in the image
  Buffer Size Requirements:
  - Optical discs: Always 2352 bytes (full raw sector)
  - Block media: User data size + tag size (varies by media type)
  - Pass data as NULL to query the exact required buffer size

Warning
  For optical discs, this function requires track information to be available. Images without track data may not support long sector reading.
  The function performs complex sector reconstruction. Corrupted metadata or missing correction data may result in incorrect sector assembly.
  Not all AaruFormat images contain the metadata necessary for long sector reading. Some images may only support basic sector reading via aaruf_read_sector().

Definition at line 826 of file read.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, aaruf_ecc_cd_reconstruct(), aaruf_ecc_cd_reconstruct_prefix(), AARUF_ERROR_BUFFER_TOO_SMALL, AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_INCORRECT_MEDIA_TYPE, AARUF_ERROR_INVALID_TRACK_FORMAT, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_NOT_ENOUGH_MEMORY, AARUF_ERROR_REACHED_UNREACHABLE_CODE, AARUF_ERROR_SECTOR_OUT_OF_BOUNDS, AARUF_ERROR_TRACK_NOT_FOUND, aaruf_read_sector(), AARUF_STATUS_OK, AARUF_STATUS_SECTOR_NOT_DUMPED, AppleFileWare, AppleProfile, AppleSonyDS, AppleSonySS, AppleWidget, Audio, BlockMedia, CD_DFIX_MASK, CD_XFIX_MASK, CdMode1, CdMode2Form1, CdMode2Form2, CdMode2Formless, Correct, Data, aaruformat_context::data_tracks, DVDDownload, DVDPR, DVDPRDL, DVDPRW, DVDPRWDL, DVDR, DVDRAM, DVDRDL, DVDROM, DVDRW, DVDRWDL, aaruformat_context::ecc_cd_context, FATAL, aaruformat_context::image_info, aaruformat_context::magic, ImageInfo::MediaType, ImageInfo::MetadataMediaType, aaruformat_context::mode2_subheaders, Mode2Form1Ok, Mode2Form2NoCrc, Mode2Form2Ok, DdtHeader2::negative, NotDumped, aaruformat_context::number_of_data_tracks, Nuon, OpticalDisc, DdtHeader2::overflow, PriamDataTower, PS2DVD, PS3DVD, SACD, aaruformat_context::sector_cpr_mai, aaruformat_context::sector_edc, aaruformat_context::sector_id, aaruformat_context::sector_ied, aaruformat_context::sector_prefix, aaruformat_context::sector_prefix_corrected, aaruformat_context::sector_prefix_ddt, aaruformat_context::sector_prefix_ddt2, aaruformat_context::sector_subchannel, aaruformat_context::sector_suffix, aaruformat_context::sector_suffix_corrected, aaruformat_context::sector_suffix_ddt, aaruformat_context::sector_suffix_ddt2, ImageInfo::Sectors, SectorStatusMode1Correct, SectorStatusMode2Form1Ok, SectorStatusMode2Form2NoCrc, SectorStatusMode2Form2Ok, SectorStatusNotDumped, TrackEntry::start, TRACE, TrackEntry::type, and aaruformat_context::user_data_ddt_header.

## ◆ aaruf_read_sector_tag()

int32_t aaruf_read_sector_tag | ( | const void * | context,
|  | const uint64_t | sector_address,
|  | const bool | negative,
|  | uint8_t * | buffer,
|  | uint32_t * | length,
|  | const int32_t | tag )

Reads a specific sector tag from the AaruFormat image.

Reads sector-level metadata tags such as subchannel data, track information, DVD sector metadata, or Apple/Priam proprietary tags from the specified sector. Sector tags are ancillary data stored separately from the main user data and provide format-specific metadata like track flags, ISRC codes, DVD encryption information, or ECC/EDC data. This function validates tag type against media type and ensures the tag data is present in the image before returning it.

Parameters

  context | Pointer to the aaruformat context.
  sector_address | The logical sector address to read the tag from.
  negative | Indicates if the sector address is negative (pre-track area).
  buffer | Pointer to buffer where tag data will be stored. Can be NULL to query tag length.
  length | Pointer to variable containing buffer size on input, actual tag length on output.
  tag | Tag identifier specifying which sector tag to read (see SectorTagType enum).

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully read the sector tag. This is returned when: The context is valid and properly initialized The requested tag type exists and is applicable to the media type The tag data is present in the image for the specified sector The provided buffer is large enough to contain the tag data The tag data is successfully copied to the output buffer The length parameter is updated with the actual tag data length
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type)
  AARUF_ERROR_SECTOR_OUT_OF_BOUNDS | (-5) The sector address exceeds image bounds. This occurs when: negative is true and sector_address > ctx->userDataDdtHeader.negative - 1 negative is false and sector_address > ctx->imageInfo.Sectors + ctx->userDataDdtHeader.overflow - 1 Attempting to read beyond the logical extent of the imaged medium
  AARUF_ERROR_INCORRECT_MEDIA_TYPE | (-12) Tag type incompatible with media type. This occurs when: Optical disc tags (CdTrackFlags, CdTrackIsrc, CdSectorSubchannel, DvdSector*) requested from BlockMedia Block media tags (AppleSonyTag, AppleProfileTag, PriamDataTowerTag) requested from OpticalDisc Tag type is specific to a media format not present in the current image
  AARUF_ERROR_INCORRECT_DATA_SIZE | (-26) The provided buffer has incorrect size. This occurs when: The buffer parameter is NULL (used for length querying - NOT an error, updates length and returns this) The buffer length (*length) doesn't match the required tag data length The length parameter is updated with the required exact size for retry
  AARUF_ERROR_SECTOR_TAG_NOT_PRESENT | (-16) The requested tag is not stored in the image. This occurs when: The tag data was not captured during the imaging process The storage pointer for the tag is NULL (e.g., ctx->sector_subchannel is NULL) The imaging hardware/software did not support reading this tag type The tag is optional and was not available on the source medium
  AARUF_ERROR_TRACK_NOT_FOUND | (-13) Track information not found for the sector. This occurs when: Requesting CdTrackFlags or CdTrackIsrc for a sector not within any track boundaries The sector address doesn't fall within any track's start/end range in ctx->trackEntries[] Track metadata was not properly initialized or is corrupted
  AARUF_ERROR_INVALID_TAG | (-27) The tag identifier is not recognized or supported. This occurs when: The tag parameter value doesn't match any known SectorTagType enum value Future/unsupported tag types not implemented in this library version

Note
  Supported Tag Types and Sizes: Optical Disc Tags (OpticalDisc media only):
  - CdTrackFlags (11): 1 byte - Track control flags (audio/data, copy permitted, pre-emphasis)
  - CdTrackIsrc (9): 12 bytes - International Standard Recording Code (no null terminator)
  - CdSectorSubchannel (71): 96 bytes - Raw P-W subchannel data
  - DvdSectorCprMai (81): 6 bytes - DVD Copyright Management Information (CPR_MAI)
  - DvdSectorInformation (16): 1 byte - DVD sector information byte from ID field
  - DvdSectorNumber (17): 3 bytes - DVD sector number from ID field
  - DvdSectorIed (84): 2 bytes - DVD ID Error Detection code
  - DvdSectorEdc (85): 4 bytes - DVD Error Detection Code
  - DvdDiscKeyDecrypted (80): 5 bytes - Decrypted DVD title key for the sector

Block Media Tags (BlockMedia only):

- AppleSonyTag (73): 12 bytes - Apple Sony format 12-byte sector tag
- AppleProfileTag (72): 20 bytes - Apple Profile format 20-byte sector tag
- PriamDataTowerTag (74): 24 bytes - Priam DataTower format 24-byte sector tag

Note
  Sector Address Correction:
  - The function automatically adjusts sector addresses based on the negative parameter
  - Negative sectors are adjusted: corrected = sector_address - ctx->userDataDdtHeader.negative
  - Positive sectors are adjusted: corrected = sector_address + ctx->userDataDdtHeader.negative
  - Corrected addresses are used for indexing into tag data arrays
  Track-Based Tags (CdTrackFlags, CdTrackIsrc):
  - These tags are per-track, not per-sector
  - Function searches ctx->trackEntries[] for track containing the sector
  - All sectors within a track return the same track-level metadata
  - Returns AARUF_ERROR_TRACK_NOT_FOUND if sector is outside all tracks
  DVD Sector Tags:
  - DVD sector tags are extracted from the DVD ID field or associated metadata
  - DvdSectorInformation and DvdSectorNumber are derived from ctx->sector_id array
  - Multiple tags may share the same underlying storage (e.g., ID field breakdown)
  - Presence depends on the DVD reading capabilities during imaging
  Buffer Size Querying:
  - Pass buffer as NULL to query the required buffer size without reading data
  - The length parameter will be updated with the exact required size
  - Returns AARUF_ERROR_INCORRECT_DATA_SIZE (not a fatal error in this context)
  - Allows proper buffer allocation before the actual read operation
  Tag Data Storage:
  - Tag data is stored in dedicated context arrays (ctx->sector_subchannel, ctx->sector_cpr_mai, etc.)
  - Each tag type has a specific array with fixed-size entries per sector
  - NULL storage pointer indicates tag was not captured/available
  - Tag data is indexed using the corrected sector address

Warning
  The buffer must be exactly the required size for each tag type. Unlike aaruf_read_sector(), this function enforces strict size matching.
  Tag availability is hardware and media dependent. Always check for AARUF_ERROR_SECTOR_TAG_NOT_PRESENT and handle gracefully.
  Track-based tags (CdTrackFlags, CdTrackIsrc) return the same value for all sectors within a track. Do not assume per-sector uniqueness.
  Some tags contain binary data without string termination (e.g., ISRC). Do not treat tag buffers as null-terminated strings without validation.

Definition at line 1474 of file read.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_INCORRECT_MEDIA_TYPE, AARUF_ERROR_INVALID_TAG, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_SECTOR_OUT_OF_BOUNDS, AARUF_ERROR_SECTOR_TAG_NOT_PRESENT, AARUF_ERROR_TRACK_NOT_FOUND, AARUF_STATUS_OK, AppleProfileTagAaru, AppleSonyTagAaru, BlockMedia, CdSectorSubchannelAaru, CdTrackFlags, CdTrackIsrc, DvdCmi, DvdSectorEdcAaru, DvdSectorIedAaru, DvdSectorInformation, DvdSectorNumber, DvdTitleKeyDecrypted, TracksHeader::entries, FATAL, TrackEntry::flags, aaruformat_context::image_info, TrackEntry::isrc, aaruformat_context::magic, ImageInfo::MetadataMediaType, DdtHeader2::negative, OpticalDisc, DdtHeader2::overflow, PriamDataTowerTagAaru, aaruformat_context::sector_cpr_mai, aaruformat_context::sector_decrypted_title_key, aaruformat_context::sector_edc, aaruformat_context::sector_id, aaruformat_context::sector_ied, aaruformat_context::sector_subchannel, ImageInfo::Sectors, TrackEntry::start, TRACE, aaruformat_context::track_entries, aaruformat_context::tracks_header, and aaruformat_context::user_data_ddt_header.

## ◆ aaruf_read_track_sector()

int32_t aaruf_read_track_sector | ( | void * | context,
|  | uint8_t * | data,
|  | const uint64_t | sector_address,
|  | uint32_t * | length,
|  | const uint8_t | track,
|  | uint8_t * | sector_status )

Reads a sector from a specific track in the AaruFormat image.

Reads user data from the specified sector address within a particular track. This function is specifically designed for optical disc images where sectors are organized by tracks. The sector address is relative to the start of the track. It validates the media type, locates the specified track by sequence number, calculates the absolute sector address, and delegates to aaruf_read_sector().

Parameters

  context | Pointer to the aaruformat context.
  data | Pointer to buffer where sector data will be stored.
  sector_address | The sector address relative to the track start.
  length | Pointer to variable containing buffer size on input, actual data length on output.
  track | The track sequence number to read from.
  sector_status | Pointer to variable that will receive the sector status flags. Must not be NULL. The status indicates the condition of the sector data, such as whether it contains errors, was not dumped, or has other quality indicators from the imaging process.

Returns
  Returns one of the following status codes:

Return values

  AARUF_STATUS_OK | (0) Successfully read the sector data from the specified track. This is returned when: The context is valid and the media type is OpticalDisc The specified track sequence number exists in the data tracks array The underlying aaruf_read_sector() call succeeds The sector data is successfully retrieved and copied to the output buffer
  AARUF_ERROR_NOT_AARUFORMAT | (-1) The context is invalid. This occurs when: The context parameter is NULL The context magic number doesn't match AARU_MAGIC (invalid context type)
  AARUF_ERROR_INCORRECT_MEDIA_TYPE | (-5) The media is not an optical disc. This occurs when: ctx->imageInfo.XmlMediaType is not OpticalDisc This function is only applicable to CD, DVD, BD, and other optical disc formats
  AARUF_ERROR_TRACK_NOT_FOUND | (-12) The specified track does not exist. This occurs when: No track in ctx->dataTracks[] has a sequence number matching the requested track The track may not contain data or may not have been imaged Only data tracks are searched; audio-only tracks are not included
  All | other error codes from aaruf_read_sector() may be returned: AARUF_STATUS_SECTOR_NOT_DUMPED (1) - Sector was not dumped during imaging AARUF_ERROR_SECTOR_OUT_OF_BOUNDS (-8) - Calculated absolute sector address exceeds image bounds AARUF_ERROR_BUFFER_TOO_SMALL (-10) - Data buffer is NULL or insufficient size AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) - Memory allocation fails during sector reading AARUF_ERROR_CANNOT_READ_HEADER (-6) - Block header cannot be read from image stream AARUF_ERROR_CANNOT_READ_BLOCK (-7) - Block data cannot be read from image stream AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17) - LZMA or FLAC decompression fails AARUF_ERROR_UNSUPPORTED_COMPRESSION (-13) - Block uses unsupported compression

Note
  Track-Relative Addressing:
  - The sector_address parameter is relative to the start of the specified track
  - The function calculates the absolute sector address as: track.start + sector_address
  - Track boundaries are defined by track.start and track.end values
  Data Track Filtering:
  - Only tracks in the ctx->dataTracks[] array are searched
  - Audio-only tracks without data content are not included in this search
  - The track sequence number is the logical track number from the disc TOC
  Function Delegation:
  - This function is a wrapper that performs track validation and address calculation
  - The actual sector reading is performed by aaruf_read_sector()
  - All caching, decompression, and DDT processing occurs in the underlying function

Warning
  This function is only applicable to optical disc media types. Attempting to use it with block media will result in AARUF_ERROR_INCORRECT_MEDIA_TYPE.
  The sector_address is relative to the track start, not the disc start. Ensure correct address calculation when working with multi-track discs.
  Track sequence numbers may not be contiguous. Always verify track existence before assuming a track number is valid.

Definition at line 670 of file read.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, AARUF_ERROR_INCORRECT_DATA_SIZE, AARUF_ERROR_INCORRECT_MEDIA_TYPE, AARUF_ERROR_NOT_AARUFORMAT, AARUF_ERROR_TRACK_NOT_FOUND, aaruf_read_sector(), aaruformat_context::data_tracks, FATAL, aaruformat_context::image_info, aaruformat_context::magic, ImageInfo::MetadataMediaType, aaruformat_context::number_of_data_tracks, OpticalDisc, TrackEntry::sequence, TrackEntry::start, and TRACE.