libaaruformat 1.0 Aaru Data Preservation Suite - Format Library

Loading...
Searching...
No Matches
TapeFileHeader Struct Reference

Header for a tape file metadata block containing file layout information. More...

`#include <aaruformat/structs/tape.h>`

## Data Fields
uint32_t | identifier
| Block type identifier.
uint32_t | entries
| Number of file entries following this header.
uint64_t | length
| Size of entry data in bytes (excluding this header).
uint64_t | crc64
| CRC64-ECMA checksum of the entry data.

## Detailed Description

Header for a tape file metadata block containing file layout information.

This structure serves as the header for a TapeFileBlock, which documents all logical files present on the tape medium. The block consists of this fixed-size header followed by a variable-length array of TapeFileEntry structures (one per file).

Block Structure:

+-------------------------+
| TapeFileHeader | <- Fixed 24-byte header
+-------------------------+
| TapeFileEntry 0 | <- First file entry
+-------------------------+
| TapeFileEntry 1 | <- Second file entry
+-------------------------+
| ... |
+-------------------------+
| TapeFileEntry (n-1) | <- Last file entry
+-------------------------+
TapeFileEntry
Describes a single logical file on a tape medium.
Definition tape.h:134
TapeFileHeader
Header for a tape file metadata block containing file layout information.
Definition tape.h:238
TapeFileEntry
struct TapeFileEntry TapeFileEntry

Purpose: The tape file block enables:

- Quick lookup of file locations without scanning the entire tape
- Validation of file boundaries and partition assignments
- Random access to specific files in the image
- Preservation of the original tape's logical organization
- Documentation of tape structure for archival purposes

Identifier Field: The identifier field must be set to BlockType::TapeFileBlock to indicate this block type. This allows the Aaru format parser to recognize and correctly interpret the block during image loading.

Entry Count: The entries field specifies the number of TapeFileEntry structures that follow the header. A tape with no files would have entries=0, though this is unusual. Maximum value is 2^32-1 (4,294,967,295 files), though practical limits are much lower.

Block Length: The length field contains the size in bytes of the data following this header (i.e., the array of TapeFileEntry structures). This is calculated as: length = entries × sizeof(TapeFileEntry)

The header itself is NOT included in the length value. Total block size is: total_size = sizeof(TapeFileHeader) + length

CRC64 Checksum: The crc64 field contains a CRC64-ECMA checksum computed over the entry data (the array of TapeFileEntry structures, excluding this header). This provides integrity verification to detect corruption in the file table. The CRC is calculated using the ECMA polynomial.

File Order: Entries should be ordered by partition number (ascending), then by file number (ascending) within each partition. This ordering facilitates efficient lookup and matches the physical organization of most tape formats.

Alignment: When written to the Aaru image, this block is aligned to the image's block alignment boundary (typically 2^blockAlignmentShift bytes). Padding may be inserted before the block to achieve proper alignment.

Index Integration: After writing this block to the image file, an IndexEntry is created with:

- blockType = TapeFileBlock
- dataType = 0 (tape file blocks have no subtype)
- offset = file position where this header was written

Note
  This block is optional. Tape images without file structure metadata can omit it, representing the tape as a simple linear sequence of blocks.
  If a tape has multiple partitions, files from all partitions are included in a single TapeFileBlock (distinguished by their Partition field).
  Empty tapes (no files) may still have a TapeFileHeader with entries=0, length=0, though such blocks are typically omitted.

Warning
  The entries count must accurately reflect the number of TapeFileEntry structures in the block. Mismatches will cause parsing errors.
  The CRC64 must be recalculated any time the entry data changes. Stale CRC values will cause integrity check failures.

See also
  TapeFileEntry for the structure of individual file entries
  TapePartitionHeader for partition structure metadata
  BlockType for block type identifier constants

Definition at line 237 of file tape.h.

## Field Documentation

## ◆ crc64

uint64_t TapeFileHeader::crc64

CRC64-ECMA checksum of the entry data.

Computed over the array of TapeFileEntry structures only. Does NOT include this header. Used for integrity verification.

Definition at line 245 of file tape.h.

Referenced by process_tape_files_block(), and write_tape_file_block().

## ◆ entries

uint32_t TapeFileHeader::entries

Number of file entries following this header.

Specifies how many TapeFileEntry structures are in this block. Valid range: 0 to 2^32-1.

Definition at line 241 of file tape.h.

Referenced by process_tape_files_block().

## ◆ identifier

uint32_t TapeFileHeader::identifier

Block type identifier.

Must be set to BlockType::TapeFileBlock. This magic value allows parsers to identify the block type.

Definition at line 239 of file tape.h.

Referenced by process_tape_files_block(), and write_tape_file_block().

## ◆ length

uint64_t TapeFileHeader::length

Size of entry data in bytes (excluding this header).

Calculated as: entries × sizeof(TapeFileEntry). This is the number of bytes following the header.

Definition at line 243 of file tape.h.

Referenced by write_tape_file_block().

The documentation for this struct was generated from the following file:

- include/aaruformat/structs/tape.h