<trclass="memdesc:a829bbac3c17b60efd8f93188a8de8278"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Processes a tape file metadata block from the image stream. <br/></td></tr>
<trclass="memdesc:aa76718b0402b1a28be3d563d5e62028e"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Processes a tape partition metadata block from the image stream. <br/></td></tr>
<trclass="memdesc:a6221f89b294ca55944944a04edb964e3"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Retrieves the block range for a specific tape file from an Aaru tape image. <br/></td></tr>
<trclass="memdesc:a03d080a18e07adc52a654dc31b26eea0"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Sets or updates the block range for a specific tape file in an Aaru tape image. <br/></td></tr>
<trclass="memdesc:a91c40d91fdeb98193d6eeb95f16d8973"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Retrieves the block range for a specific tape partition from an Aaru tape image. <br/></td></tr>
<trclass="memdesc:aa16d4457093df66246ce5622c3565a17"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Sets or updates the block range for a specific tape partition in an Aaru tape image. <br/></td></tr>
<trclass="memdesc:ad4f8c223fb7c48a03ac4120d12e657b3"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Retrieves all tape file entries from the image. <br/></td></tr>
<trclass="memdesc:a2c3aa323e7217e4d25b895a094a34cd0"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Retrieves all tape partition entries from the image. <br/></td></tr>
<p>Retrieves all tape file entries from the image. </p>
<p>Extracts the complete set of tape file metadata entries from an Aaru tape image, returning an array of <aclass="el"href="structTapeFileEntry.html"title="Describes a single logical file on a tape medium.">TapeFileEntry</a> structures. Tape files represent logical file divisions on sequential access media (magnetic tapes) where data is organized into numbered files within numbered partitions. Each file entry defines a contiguous range of tape blocks (FirstBlock to LastBlock inclusive) that comprise one logical file unit on the tape medium.</p>
<p>Tape file organization is hierarchical:</p><ul>
<li><b>Partition</b>: Physical or logical division of the tape (0-255)</li>
<li><b>File</b>: Numbered file within a partition (0-4,294,967,295)</li>
<li><b>Block Range</b>: Contiguous sequence of tape blocks containing the file data</li>
</ul>
<p>This function is essential for applications that need to:</p><ul>
<li>Enumerate all logical files stored on a tape image</li>
<li>Build file system catalogs or directory structures for tape media</li>
<li>Implement tape navigation and seeking operations</li>
<li>Extract individual files from multi-file tape archives</li>
<li>Verify tape image completeness and structure</li>
<li>Generate tape content manifests for archival documentation</li>
</ul>
<p>The function supports a two-call pattern for buffer size determination:</p><oltype="1">
<li>First call with NULL buffer or insufficient length returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size (entry_count × sizeof(TapeFileEntry))</li>
<li>Second call with properly sized buffer retrieves all file entries</li>
</ol>
<p>Alternatively, if the caller knows or pre-allocates sufficient buffer space, a single call will succeed and populate the buffer with all tape file entries.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened tape image context). </td></tr>
<tr><tdclass="paramname">buffer</td><td>Pointer to a buffer that will receive the array of <aclass="el"href="structTapeFileEntry.html"title="Describes a single logical file on a tape medium.">TapeFileEntry</a> structures. May be NULL to query the required buffer size without retrieving data. </td></tr>
<tr><tdclass="paramname">length</td><td>Pointer to a size_t that serves dual purpose:<ul>
<li>On input: size of the provided buffer in bytes (ignored if buffer is NULL)</li>
<li>On output: actual size required/used for all entries in bytes</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved all tape file entries. </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_TAPE_FILE_NOT_FOUND</td><td>(-19) No tape file metadata exists. </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-12) The provided buffer is insufficient.</td></tr>
</table>
</dd>
</dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#a6221f89b294ca55944944a04edb964e3"title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> to retrieve a specific file's block range </dd>
<dd>
<aclass="el"href="#a03d080a18e07adc52a654dc31b26eea0"title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> to define or update a tape file entry </dd>
<dd>
<aclass="el"href="#a2c3aa323e7217e4d25b895a094a34cd0"title="Retrieves all tape partition entries from the image.">aaruf_get_all_tape_partitions()</a> to retrieve partition boundaries </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l01314">1314</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<p>Retrieves all tape partition entries from the image. </p>
<p>Extracts the complete set of tape partition metadata entries from an Aaru tape image, returning an array of <aclass="el"href="structTapePartitionEntry.html"title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> structures. Tape partitions represent physical or logical divisions of sequential access media (magnetic tapes) that segment the tape into independent data regions. Each partition entry defines a contiguous range of tape blocks (FirstBlock to LastBlock inclusive) that comprise one partition on the tape medium.</p>
<p>Tape partitions enable:</p><ul>
<li><b>Multi-partition tapes</b>: Modern tape formats (LTO-5+, SDLT) support multiple partitions</li>
<li><b>Data organization</b>: Separating metadata, indexes, and data into distinct partitions</li>
<li><b>Fast access</b>: Partition switching is faster than sequential seeking across the entire tape</li>
<li><b>Logical separation</b>: Isolating different data sets or file systems on the same tape</li>
</ul>
<p>This function is essential for applications that need to:</p><ul>
<li>Enumerate all partitions on a multi-partition tape image</li>
<li>Determine partition boundaries and sizes for navigation</li>
<li>Implement partition-aware file system drivers or extraction tools</li>
<li>Validate tape structure and partition layout integrity</li>
<li>Generate tape structure documentation for archival purposes</li>
</ul>
<p>The function supports a two-call pattern for buffer size determination:</p><oltype="1">
<li>First call with NULL buffer or insufficient length returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size (partition_count × sizeof(TapePartitionEntry))</li>
<li>Second call with properly sized buffer retrieves all partition entries</li>
</ol>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, opened tape image context). </td></tr>
<tr><tdclass="paramname">buffer</td><td>Pointer to a buffer that will receive the array of <aclass="el"href="structTapePartitionEntry.html"title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> structures. May be NULL to query the required buffer size without retrieving data. </td></tr>
<tr><tdclass="paramname">length</td><td>Pointer to a size_t that serves dual purpose:<ul>
<li>On input: size of the provided buffer in bytes (ignored if buffer is NULL)</li>
<li>On output: actual size required/used for all entries in bytes</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved all tape partition entries. </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_TAPE_PARTITION_NOT_FOUND</td><td>(-20) No tape partition metadata exists. </td></tr>
<tr><tdclass="paramname">AARUF_ERROR_BUFFER_TOO_SMALL</td><td>(-12) The provided buffer is insufficient.</td></tr>
</table>
</dd>
</dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#a91c40d91fdeb98193d6eeb95f16d8973"title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> to retrieve a specific partition's block range </dd>
<dd>
<aclass="el"href="#aa16d4457093df66246ce5622c3565a17"title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> to define or update a tape partition entry </dd>
<dd>
<aclass="el"href="#ad4f8c223fb7c48a03ac4120d12e657b3"title="Retrieves all tape file entries from the image.">aaruf_get_all_tape_files()</a> to retrieve all tape file entries </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l01416">1416</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<p>Retrieves the block range for a specific tape file from an Aaru tape image. </p>
<p>Queries the tape file hash table to locate a file by its partition and file number, returning the first and last block addresses that define the file's extent on the tape medium. This function provides the core lookup mechanism for accessing logical files stored in tape images.</p>
<p><b>Tape File Identification:</b> Each tape file is uniquely identified by a combination of:</p><ul>
<li><b>Partition number</b> (8-bit): The tape partition containing the file</li>
<li><b>File number</b> (32-bit): The sequential file number within that partition</li>
</ul>
<p>These two values are combined into a 64-bit composite key: key = (partition << 32) | file_number</p>
<p>This composite key is used to perform a hash table lookup in the context's tapeFiles table, which was previously populated by <aclass="el"href="#a829bbac3c17b60efd8f93188a8de8278"title="Processes a tape file metadata block from the image stream.">process_tape_files_block()</a> during image initialization.</p>
<p><b>Block Range Semantics:</b> The returned block range [FirstBlock, LastBlock] is inclusive on both ends:</p><ul>
<li>FirstBlock: The first block address where the file begins</li>
<li>LastBlock: The final block address where the file ends (inclusive)</li>
<p>Block addresses are absolute positions within the tape image's logical block space, not relative to the partition or file.</p>
<p><b>Typical Usage Flow:</b></p><oltype="1">
<li>Open an Aaru tape image with <aclass="el"href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656"title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
<li>Call <aclass="el"href="#a6221f89b294ca55944944a04edb964e3"title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> to get the block range for a specific file</li>
<li>Use the returned block range to read the file's data blocks</li>
<li>Repeat for other files as needed</li>
</ol>
<p><b>Error Handling:</b> The function performs validation in the following order:</p><oltype="1">
<li>Context pointer validation (NULL check)</li>
<li>Magic number verification (ensures valid aaruformat context)</li>
<li>Hash table lookup for the specified partition/file combination</li>
</ol>
<p>If any validation fails, an appropriate error code is returned and the output parameters (starting_block, ending_block) are left unmodified.</p>
<p><b>Thread Safety:</b> This function performs read-only operations on the context and is safe to call from multiple threads concurrently, provided the context is not being modified by other operations (e.g., during image opening/closing).</p>
<p><b>Performance Characteristics:</b></p><ul>
<li>Hash table lookup: O(1) average case</li>
<li>No I/O operations performed</li>
<li>Minimal stack usage</li>
<li>Suitable for high-frequency queries</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramdir"></td><tdclass="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been successfully opened with <aclass="el"href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656"title="Opens an existing AaruFormat image file.">aaruf_open()</a> and contain a valid tape file hash table. The context is treated as const and is not modified by this operation.</td></tr>
<tr><tdclass="paramdir"></td><tdclass="paramname">partition</td><td>The partition number (0-255) containing the requested file. For single-partition tapes, this is typically 0. Multi-partition tapes may have files in different partitions with potentially overlapping file numbers.</td></tr>
<tr><tdclass="paramdir"></td><tdclass="paramname">file</td><td>The file number within the specified partition. File numbers are typically sequential starting from 0 or 1, but gaps may exist if files were deleted or the tape was written non-sequentially.</td></tr>
<tr><tdclass="paramdir">[out]</td><tdclass="paramname">starting_block</td><td>Pointer to receive the first block address of the file. Must not be NULL. Only modified on success. The value written represents the inclusive start of the file's block range.</td></tr>
<tr><tdclass="paramdir">[out]</td><tdclass="paramname">ending_block</td><td>Pointer to receive the last block address of the file. Must not be NULL. Only modified on success. The value written represents the inclusive end of the file's block range.</td></tr>
</table>
</dd>
</dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved tape file information. Both output parameters have been populated with valid block addresses. The requested partition/file combination exists in the image's file table.</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
<li>The context pointer is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) The output parameters are not modified.</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_TAPE_FILE_NOT_FOUND</td><td>(-28) The requested partition/file combination does not exist in the image's tape file table. This is returned when:<ul>
<li>The specified partition number has no files</li>
<li>The specified file number doesn't exist in the given partition</li>
<li>The tape file block was not present or failed to load during image open The output parameters are not modified.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
<dd>
The tape file hash table (ctx->tapeFiles) must have been populated during image initialization. If the image doesn't contain a TapeFileBlock, or if that block failed to load, all queries will return AARUF_ERROR_TAPE_FILE_NOT_FOUND.</dd>
<dd>
For images without tape file metadata, applications should fall back to direct block-based access or partition-level operations.</dd>
<dd>
The returned block addresses are logical block numbers. To read actual data, these must be translated through the appropriate read functions that handle the image's block encoding, compression, and DDT mapping.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The output parameter pointers must be valid. Passing NULL for either starting_block or ending_block will cause undefined behavior (likely a crash when the function attempts to dereference them on success).</dd>
<dd>
If the same partition/file combination appears multiple times in the TapeFileBlock, only the last occurrence is retained (due to HASH_REPLACE behavior in process_tape_files_block). This should not occur in valid images but may happen with corrupted or malformed tape file metadata.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#a829bbac3c17b60efd8f93188a8de8278"title="Processes a tape file metadata block from the image stream.">process_tape_files_block()</a> for tape file table initialization </dd>
<dd>
<aclass="el"href="structTapeFileEntry.html"title="Describes a single logical file on a tape medium.">TapeFileEntry</a> for the structure defining file block ranges </dd>
<dd>
<aclass="el"href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a> for the hash table entry structure </dd>
<dd>
<aclass="el"href="#a91c40d91fdeb98193d6eeb95f16d8973"title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> for partition-level queries (if available) </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l00569">569</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<p>Retrieves the block range for a specific tape partition from an Aaru tape image. </p>
<p>Queries the tape partition hash table to locate a partition by its partition number, returning the first and last block addresses that define the partition's extent on the tape medium. This function provides the core lookup mechanism for accessing partition layout information in tape images.</p>
<p><b>Tape Partition Identification:</b> Each tape partition is uniquely identified by its partition number (0-255). Most tapes have a single partition (partition 0), but multi-partition formats like LTO, DLT, and AIT support multiple partitions with independent block address spaces.</p>
<p>The partition number is used as the hash table key to perform a lookup in the context's tapePartitions table, which was previously populated by <aclass="el"href="#aa76718b0402b1a28be3d563d5e62028e"title="Processes a tape partition metadata block from the image stream.">process_tape_partitions_block()</a> during image initialization.</p>
<p><b>Block Range Semantics:</b> The returned block range [FirstBlock, LastBlock] is inclusive on both ends:</p><ul>
<li>FirstBlock: The first block address in the partition (often 0, but format-dependent)</li>
<li>LastBlock: The final block address in the partition (inclusive)</li>
<p>Block addresses are local to each partition. Different partitions may have overlapping logical block numbers (e.g., both partition 0 and partition 1 can have blocks 0-1000). When accessing blocks, both the partition number and block number are required for unique identification.</p>
<p><b>Typical Usage Flow:</b></p><oltype="1">
<li>Open an Aaru tape image with <aclass="el"href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656"title="Opens an existing AaruFormat image file.">aaruf_open()</a></li>
<li>Call <aclass="el"href="#a91c40d91fdeb98193d6eeb95f16d8973"title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> to get the block range for a specific partition</li>
<li>Use the returned block range to understand partition boundaries</li>
<li>Access files within the partition using <aclass="el"href="#a6221f89b294ca55944944a04edb964e3"title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a></li>
<li>Repeat for other partitions as needed</li>
</ol>
<p><b>Error Handling:</b> The function performs validation in the following order:</p><oltype="1">
<li>Context pointer validation (NULL check)</li>
<li>Magic number verification (ensures valid aaruformat context)</li>
<li>Hash table lookup for the specified partition number</li>
</ol>
<p>If any validation fails, an appropriate error code is returned and the output parameters (starting_block, ending_block) are left unmodified.</p>
<p><b>Thread Safety:</b> This function performs read-only operations on the context and is safe to call from multiple threads concurrently, provided the context is not being modified by other operations (e.g., during image opening/closing).</p>
<p><b>Performance Characteristics:</b></p><ul>
<li>Hash table lookup: O(1) average case</li>
<li>No I/O operations performed</li>
<li>Minimal stack usage</li>
<li>Suitable for high-frequency queries</li>
</ul>
<p><b>Partition Layout Information:</b> The partition metadata is essential for:</p><ul>
<li>Understanding the physical organization of the tape</li>
<li>Determining partition boundaries for file access</li>
<li>Validating that file block ranges fall within partition limits</li>
<li>Preserving original tape partitioning schemes</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramdir"></td><tdclass="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been successfully opened with <aclass="el"href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656"title="Opens an existing AaruFormat image file.">aaruf_open()</a> and contain a valid tape partition hash table. The context is treated as const and is not modified by this operation.</td></tr>
<tr><tdclass="paramdir"></td><tdclass="paramname">partition</td><td>The partition number (0-255) to query. For single-partition tapes, this is typically 0. Multi-partition tapes may have multiple partitions numbered sequentially from 0.</td></tr>
<tr><tdclass="paramdir">[out]</td><tdclass="paramname">starting_block</td><td>Pointer to receive the first block address of the partition. Must not be NULL. Only modified on success. The value written represents the inclusive start of the partition's block range (often 0, but format-dependent).</td></tr>
<tr><tdclass="paramdir">[out]</td><tdclass="paramname">ending_block</td><td>Pointer to receive the last block address of the partition. Must not be NULL. Only modified on success. The value written represents the inclusive end of the partition's block range.</td></tr>
</table>
</dd>
</dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully retrieved tape partition information. Both output parameters have been populated with valid block addresses. The requested partition exists in the image's partition table.</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
<li>The context pointer is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) The output parameters are not modified.</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_TAPE_PARTITION_NOT_FOUND</td><td>(-29) The requested partition number does not exist in the image's tape partition table. This is returned when:<ul>
<li>The specified partition number was not defined in the TapePartitionBlock</li>
<li>The tape partition block was not present or failed to load during image open</li>
<li>The partition number is out of range for this tape The output parameters are not modified.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
<dd>
The tape partition hash table (ctx->tapePartitions) must have been populated during image initialization. If the image doesn't contain a TapePartitionBlock, or if that block failed to load, all queries will return AARUF_ERROR_TAPE_PARTITION_NOT_FOUND.</dd>
<dd>
For images without tape partition metadata, the entire tape may be treated as a single implicit partition, and applications should handle the absence of partition information gracefully.</dd>
<dd>
The returned block addresses are logical block numbers within the partition's address space. To read actual data, these must be combined with the partition number and translated through the appropriate read functions.</dd>
<dd>
Partition metadata is primarily informational and used for validation. File access is primarily driven by file metadata (TapeFileBlock), which references partition numbers to establish context.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The output parameter pointers must be valid. Passing NULL for either starting_block or ending_block will cause undefined behavior (likely a crash when the function attempts to dereference them on success).</dd>
<dd>
If the same partition number appears multiple times in the TapePartitionBlock, only the last occurrence is retained (due to HASH_REPLACE behavior in process_tape_partitions_block). This should not occur in valid images but may happen with corrupted or malformed partition metadata.</dd>
<dd>
Single-partition tapes may not include a TapePartitionBlock at all, in which case this function will always return AARUF_ERROR_TAPE_PARTITION_NOT_FOUND. Applications should handle this case and assume a default partition 0 spanning the entire tape.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#aa76718b0402b1a28be3d563d5e62028e"title="Processes a tape partition metadata block from the image stream.">process_tape_partitions_block()</a> for partition table initialization </dd>
<dd>
<aclass="el"href="structTapePartitionEntry.html"title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> for the structure defining partition block ranges </dd>
<dd>
<aclass="el"href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a> for the hash table entry structure </dd>
<dd>
<aclass="el"href="#a6221f89b294ca55944944a04edb964e3"title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> for file-level queries within partitions </dd>
<dd>
<aclass="el"href="#aa16d4457093df66246ce5622c3565a17"title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> for setting partition information during write </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l00982">982</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<p>Sets or updates the block range for a specific tape file in an Aaru tape image. </p>
<p>Creates or modifies a tape file entry in the context's hash table, defining the logical file's extent on the tape medium by its partition number, file number, and block range. This function is the write-mode counterpart to <aclass="el"href="#a6221f89b294ca55944944a04edb964e3"title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> and is used when creating or modifying tape images to establish the file structure metadata.</p>
<p><b>Tape File Registration:</b> When writing a tape image, this function should be called for each logical file to register its location. Each file is uniquely identified by:</p><ul>
<li><b>Partition number</b> (8-bit): The tape partition containing the file</li>
<li><b>File number</b> (32-bit): The sequential file number within that partition</li>
</ul>
<p>These values are combined into a 64-bit composite key: key = (partition << 32) | file_number</p>
<p>The file entry (including the block range) is then stored in the context's tapeFiles hash table and will be written to the image's TapeFileBlock during finalization.</p>
<p><b>Block Range Definition:</b> The block range [starting_block, ending_block] defines the file's extent:</p><ul>
<li>starting_block: The first block address where the file begins (inclusive)</li>
<li>ending_block: The final block address where the file ends (inclusive)</li>
<p>Block addresses must be absolute positions within the tape image's logical block space. The caller is responsible for ensuring:</p><ul>
<li>starting_block <= ending_block (no validation is performed)</li>
<li>Block ranges don't conflict with other files (no validation is performed)</li>
<li>All blocks in the range have been or will be written to the image</li>
</ul>
<p><b>Typical Usage Flow:</b></p><oltype="1">
<li>Open or create an Aaru tape image with write access</li>
<li>Write the file's data blocks to the image</li>
<li>Call <aclass="el"href="#a03d080a18e07adc52a654dc31b26eea0"title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> to register the file's block range</li>
<li>Repeat for all files on the tape</li>
<li>Close the image (TapeFileBlock will be written during finalization)</li>
</ol>
<p><b>Update/Replace Behavior:</b> If a file entry with the same partition/file combination already exists:</p><ul>
<li>The old entry is automatically freed</li>
<li>The new entry replaces it in the hash table</li>
<li>A TRACE message indicates the replacement</li>
</ul>
<p>This allows updating file metadata or correcting errors without manual deletion.</p>
<p><b>Error Handling:</b> The function performs validation in the following order:</p><oltype="1">
<li>Context pointer validation (NULL check)</li>
<li>Magic number verification (ensures valid aaruformat context)</li>
<li>Write mode verification (ensures image is opened for writing)</li>
<li>Memory allocation for the hash entry</li>
</ol>
<p>If any validation fails, an appropriate error code is returned and no modifications are made to the context's tape file table.</p>
<p><b>Thread Safety:</b> This function modifies the shared context's hash table and is NOT thread-safe. Concurrent calls to <aclass="el"href="#a03d080a18e07adc52a654dc31b26eea0"title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> or other functions that modify ctx->tapeFiles may result in data corruption or memory leaks. The caller must ensure exclusive access through external synchronization if needed.</p>
<p><b>Memory Management:</b></p><ul>
<li>Allocates a new hash table entry (<aclass="el"href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a>) for each call</li>
<li>All hash entries are freed when the context is closed</li>
<li>On allocation failure, no entry is added and an error is returned</li>
</ul>
<p><b>Performance Characteristics:</b></p><ul>
<li>Hash table insertion/replacement: O(1) average case</li>
<li>No I/O operations performed (metadata written during image close)</li>
<li>Minimal stack usage</li>
<li>Suitable for bulk file registration operations</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been opened with write access (isWriting=true). The context's tapeFiles hash table will be updated with the new entry.</td></tr>
<tr><tdclass="paramname">partition</td><td>The partition number (0-255) where the file is located. For single-partition tapes, this is typically 0. Multi-partition tapes can have files in different partitions with potentially overlapping file numbers.</td></tr>
<tr><tdclass="paramname">file</td><td>The file number within the specified partition. File numbers are typically sequential (0, 1, 2, ...) but gaps are allowed. The same file number can exist in different partitions without conflict.</td></tr>
<tr><tdclass="paramname">starting_block</td><td>The first block address of the file (inclusive). This should be the absolute block number in the image where the file's first byte begins. Must be <= ending_block (not validated).</td></tr>
<tr><tdclass="paramname">ending_block</td><td>The last block address of the file (inclusive). This should be the absolute block number in the image where the file's last byte ends. Must be >= starting_block (not validated).</td></tr>
</table>
</dd>
</dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully set tape file information. The hash table has been updated with the file entry. If an entry with the same partition/file combination existed, it has been replaced. The metadata will be written to the TapeFileBlock when the image is closed.</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
<li>The context pointer is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) No modifications are made to the context.</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_READ_ONLY</td><td>(-22) The context is not opened for writing. This is returned when ctx->isWriting is false, indicating the image was opened in read-only mode. Tape file metadata cannot be modified in read-only mode. No modifications are made to the context.</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. The system could not allocate memory for the hash table entry (<aclass="el"href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a>). This is a critical error indicating low memory conditions. No modifications are made to the context.</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
<dd>
The tape file metadata is not immediately written to disk. It remains in the context's hash table until the image is closed, at which point all entries are serialized and written to a TapeFileBlock.</dd>
<dd>
No validation is performed on the block range values. The caller is responsible for ensuring that starting_block <= ending_block and that the range is valid for the image being created.</dd>
<dd>
No validation is performed to detect overlapping file ranges. Multiple files can reference the same or overlapping block ranges, which may be intentional (e.g., for multi-track or multi-partition scenarios).</dd>
<dd>
If the same partition/file combination is set multiple times, only the last values are retained. This can be used to update file metadata but also means accidental duplicate calls will silently overwrite previous values.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>This function is NOT thread-safe. Concurrent modifications to the tape file table may result in undefined behavior, memory corruption, or memory leaks.</dd>
<dd>
The caller must ensure the image is opened with write access before calling this function. Attempting to modify read-only images will fail with AARUF_READ_ONLY.</dd>
<dd>
Parameter validation is minimal. Invalid block ranges (starting_block > ending_block) are accepted and will be written to the image, potentially causing problems when reading the image later.</dd>
<dd>
If memory allocation fails (AARUF_ERROR_NOT_ENOUGH_MEMORY), the file entry is not added. The caller should handle this error appropriately, potentially by freeing memory and retrying or aborting the write operation.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#a6221f89b294ca55944944a04edb964e3"title="Retrieves the block range for a specific tape file from an Aaru tape image.">aaruf_get_tape_file()</a> for retrieving tape file information from images </dd>
<dd>
<aclass="el"href="#a829bbac3c17b60efd8f93188a8de8278"title="Processes a tape file metadata block from the image stream.">process_tape_files_block()</a> for tape file table initialization during read </dd>
<dd>
<aclass="el"href="structTapeFileEntry.html"title="Describes a single logical file on a tape medium.">TapeFileEntry</a> for the structure defining file block ranges </dd>
<dd>
<aclass="el"href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a> for the hash table entry structure </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l00770">770</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<p>Sets or updates the block range for a specific tape partition in an Aaru tape image. </p>
<p>Creates or modifies a tape partition entry in the context's hash table, defining the physical partition's extent on the tape medium by its partition number and block range. This function is the write-mode counterpart to <aclass="el"href="#a91c40d91fdeb98193d6eeb95f16d8973"title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> and is used when creating or modifying tape images to establish the partition structure metadata.</p>
<p><b>Tape Partition Registration:</b> When writing a tape image, this function should be called for each physical partition to register its block range. Each partition is uniquely identified by its partition number (0-255), and most tapes have a single partition (partition 0), though formats like LTO, DLT, and AIT support multiple partitions.</p>
<p>The partition entry (including the block range) is stored in the context's tapePartitions hash table and will be written to the image's TapePartitionBlock during finalization.</p>
<p><b>Block Range Definition:</b> The block range [starting_block, ending_block] defines the partition's extent:</p><ul>
<li>starting_block: The first block address in the partition (often 0, but format-dependent)</li>
<li>ending_block: The final block address in the partition (inclusive)</li>
<p>Block addresses are local to each partition. The caller is responsible for ensuring:</p><ul>
<li>starting_block <= ending_block (no validation is performed)</li>
<li>Partition ranges don't overlap (no validation is performed)</li>
<li>All blocks in the range have been or will be written to the image</li>
<li>Files referencing this partition have block addresses within this range</li>
</ul>
<p><b>Typical Usage Flow:</b></p><oltype="1">
<li>Open or create an Aaru tape image with write access</li>
<li>Define partition layout by calling <aclass="el"href="#aa16d4457093df66246ce5622c3565a17"title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> for each partition</li>
<li>Write data blocks to the image within the defined partition ranges</li>
<li>Register files within partitions using <aclass="el"href="#a03d080a18e07adc52a654dc31b26eea0"title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a></li>
<li>Close the image (TapePartitionBlock will be written during finalization)</li>
</ol>
<p><b>Update/Replace Behavior:</b> If a partition entry with the same partition number already exists:</p><ul>
<li>The old entry is automatically freed</li>
<li>The new entry replaces it in the hash table</li>
<li>A TRACE message indicates the replacement</li>
</ul>
<p>This allows updating partition metadata or correcting errors without manual deletion.</p>
<p><b>Error Handling:</b> The function performs validation in the following order:</p><oltype="1">
<li>Context pointer validation (NULL check)</li>
<li>Magic number verification (ensures valid aaruformat context)</li>
<li>Write mode verification (ensures image is opened for writing)</li>
<li>Memory allocation for the hash entry</li>
</ol>
<p>If any validation fails, an appropriate error code is returned and no modifications are made to the context's tape partition table.</p>
<p><b>Thread Safety:</b> This function modifies the shared context's hash table and is NOT thread-safe. Concurrent calls to <aclass="el"href="#aa16d4457093df66246ce5622c3565a17"title="Sets or updates the block range for a specific tape partition in an Aaru tape image.">aaruf_set_tape_partition()</a> or other functions that modify ctx->tapePartitions may result in data corruption or memory leaks. The caller must ensure exclusive access through external synchronization if needed.</p>
<p><b>Memory Management:</b></p><ul>
<li>Allocates a new hash table entry (<aclass="el"href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a>) for each call</li>
<li>All hash entries are freed when the context is closed</li>
<li>On allocation failure, no entry is added and an error is returned</li>
</ul>
<p><b>Performance Characteristics:</b></p><ul>
<li>Hash table insertion/replacement: O(1) average case</li>
<li>No I/O operations performed (metadata written during image close)</li>
<li>Minimal stack usage</li>
<li>Suitable for bulk partition registration operations</li>
</ul>
<p><b>Partition Organization:</b> Proper partition metadata is essential for:</p><ul>
<li>Documenting the physical layout of multi-partition tapes</li>
<li>Validating file block ranges against partition boundaries</li>
<li>Preserving the original tape's partitioning scheme for archival purposes</li>
<li>Supporting tape formats that require specific partition structures</li>
<li>Enabling applications to understand and navigate complex tape layouts</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to an initialized aaruformat context. Must not be NULL. The context must have been opened with write access (isWriting=true). The context's tapePartitions hash table will be updated with the new entry.</td></tr>
<tr><tdclass="paramname">partition</td><td>The partition number (0-255) to set. For single-partition tapes, this is typically 0. Multi-partition tapes use sequential numbers (0, 1, 2, ...) though the numbering scheme is format-specific.</td></tr>
<tr><tdclass="paramname">starting_block</td><td>The first block address of the partition (inclusive). This defines where the partition begins in the tape's block address space. Often 0 for the first partition, but format-dependent. Must be <= ending_block (not validated).</td></tr>
<tr><tdclass="paramname">ending_block</td><td>The last block address of the partition (inclusive). This defines where the partition ends in the tape's block address space. Must be >= starting_block (not validated).</td></tr>
</table>
</dd>
</dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">AARUF_STATUS_OK</td><td>(0) Successfully set tape partition information. The hash table has been updated with the partition entry. If an entry with the same partition number existed, it has been replaced. The metadata will be written to the TapePartitionBlock when the image is closed.</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or context validation failed. This is returned when:<ul>
<li>The context pointer is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (corrupted or wrong type) No modifications are made to the context.</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_READ_ONLY</td><td>(-22) The context is not opened for writing. This is returned when ctx->isWriting is false, indicating the image was opened in read-only mode. Tape partition metadata cannot be modified in read-only mode. No modifications are made to the context.</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. The system could not allocate memory for the hash table entry (<aclass="el"href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a>). This is a critical error indicating low memory conditions. No modifications are made to the context.</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>The function logs entry and exit points via TRACE macros when tracing is enabled, including parameter values and return codes for debugging.</dd>
<dd>
The tape partition metadata is not immediately written to disk. It remains in the context's hash table until the image is closed, at which point all entries are serialized and written to a TapePartitionBlock.</dd>
<dd>
No validation is performed on the block range values. The caller is responsible for ensuring that starting_block <= ending_block and that the range is valid for the image being created.</dd>
<dd>
No validation is performed to detect overlapping partition ranges. Partitions with overlapping block addresses may be accepted but will likely cause problems when reading the image or accessing files.</dd>
<dd>
If the same partition number is set multiple times, only the last values are retained. This can be used to update partition metadata but also means accidental duplicate calls will silently overwrite previous values.</dd>
<dd>
For single-partition tapes, it may be acceptable to omit the TapePartitionBlock entirely. Applications reading such images should assume a default partition 0 spanning the entire tape if no partition metadata is present.</dd>
<dd>
Block addresses are local to each partition. Files within a partition reference blocks relative to that partition's address space, not the global tape address space (though in practice, many formats use absolute addressing).</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>This function is NOT thread-safe. Concurrent modifications to the tape partition table may result in undefined behavior, memory corruption, or memory leaks.</dd>
<dd>
The caller must ensure the image is opened with write access before calling this function. Attempting to modify read-only images will fail with AARUF_READ_ONLY.</dd>
<dd>
Parameter validation is minimal. Invalid block ranges (starting_block > ending_block) are accepted and will be written to the image, potentially causing problems when reading the image later.</dd>
<dd>
If memory allocation fails (AARUF_ERROR_NOT_ENOUGH_MEMORY), the partition entry is not added. The caller should handle this error appropriately, potentially by freeing memory and retrying or aborting the write operation.</dd>
<dd>
Partition metadata should be consistent with file metadata. Files should only reference partitions that have been defined, and their block ranges should fall within the partition boundaries. No automatic validation is performed.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="#a91c40d91fdeb98193d6eeb95f16d8973"title="Retrieves the block range for a specific tape partition from an Aaru tape image.">aaruf_get_tape_partition()</a> for retrieving tape partition information from images </dd>
<dd>
<aclass="el"href="#aa76718b0402b1a28be3d563d5e62028e"title="Processes a tape partition metadata block from the image stream.">process_tape_partitions_block()</a> for partition table initialization during read </dd>
<dd>
<aclass="el"href="structTapePartitionEntry.html"title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> for the structure defining partition block ranges </dd>
<dd>
<aclass="el"href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a> for the hash table entry structure </dd>
<dd>
<aclass="el"href="#a03d080a18e07adc52a654dc31b26eea0"title="Sets or updates the block range for a specific tape file in an Aaru tape image.">aaruf_set_tape_file()</a> for setting file metadata within partitions </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l01196">1196</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<p>Processes a tape file metadata block from the image stream. </p>
<p>Reads and parses a TapeFileBlock from the Aaru image, validates its integrity, and populates the context's tape file hash table with file layout information. Each tape file entry defines a logical file on the tape medium by specifying its partition, file number, and block range (FirstBlock to LastBlock inclusive).</p>
<p>The function performs the following operations:</p><oltype="1">
<li>Seeks to the block position indicated by the index entry</li>
<li>Reads and validates the <aclass="el"href="structTapeFileHeader.html"title="Header for a tape file metadata block containing file layout information.">TapeFileHeader</a> structure</li>
<li>Allocates and reads the array of <aclass="el"href="structTapeFileEntry.html"title="Describes a single logical file on a tape medium.">TapeFileEntry</a> structures</li>
<li>Validates data integrity using CRC64-ECMA checksum</li>
<li>Inserts each file entry into the context's UTHASH table with a composite key</li>
<li>Updates image size statistics</li>
</ol>
<p><b>Composite Key Construction:</b> Each tape file is uniquely identified by a 64-bit composite key: key = (partition << 32) | file_number This allows files with the same file number in different partitions to coexist in the hash table without conflicts.</p>
<p><b>Hash Table Management:</b> The function uses HASH_REPLACE to insert entries, which automatically:</p><ul>
<li>Adds new entries if the key doesn't exist</li>
<li>Replaces existing entries if the key is found (freeing the old entry) This ensures that duplicate entries (same partition/file combination) are properly handled by keeping only the most recent definition.</li>
</ul>
<p><b>Error Handling:</b> The function treats most errors as non-fatal and continues processing:</p><ul>
<li>Invalid context or stream: Returns immediately (FATAL log)</li>
<divclass="ttc"id="astructTapeFileEntry_html"><divclass="ttname"><ahref="structTapeFileEntry.html">TapeFileEntry</a></div><divclass="ttdoc">Describes a single logical file on a tape medium.</div><divclass="ttdef"><b>Definition</b><ahref="tape_8h_source.html#l00133">tape.h:134</a></div></div>
</div><!-- fragment --><p><b>CRC64 Validation:</b> The CRC64 checksum in the header is computed over the entire array of <aclass="el"href="structTapeFileEntry.html"title="Describes a single logical file on a tape medium.">TapeFileEntry</a> structures (excluding the header itself). This provides integrity verification to detect corruption in the file table.</p>
<p><b>Memory Management:</b></p><ul>
<li>Allocates a temporary buffer to read all file entries</li>
<li>Allocates individual hash table entries for each file</li>
<li>Frees the temporary buffer before returning</li>
<li>Hash table entries remain in context until cleanup</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context. Must not be NULL. The context must have a valid imageStream open for reading. The ctx->tapeFiles hash table will be populated with file entries. The ctx->imageInfo.ImageSize will be updated with the block size.</td></tr>
<tr><tdclass="paramname">entry</td><td>Pointer to the index entry describing the tape file block. Must not be NULL. The entry->offset field indicates the file position where the <aclass="el"href="structTapeFileHeader.html"title="Header for a tape file metadata block containing file layout information.">TapeFileHeader</a> begins.</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>This function does not return a status code. All errors are handled internally with appropriate logging and the function returns early on fatal errors.</dd>
<dd>
The tape file hash table (ctx->tapeFiles) must be initialized to NULL before the first call to this function. UTHASH will manage the table automatically as entries are added.</dd>
<dd>
Files are ordered in the hash table by their composite key value, not by insertion order. To iterate files in partition/file number order, use HASH_SORT with an appropriate comparison function.</dd>
<dd>
The function updates ctx->imageInfo.ImageSize by adding the size of all file entries (entries × sizeof(TapeFileEntry)). This contributes to the total reported image size but does not include the header size.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The context and imageStream must be valid. Passing NULL pointers will result in immediate return with a FATAL log message.</dd>
<dd>
If the CRC64 checksum validation fails, all entries in the block are discarded. The function does not attempt partial recovery.</dd>
<dd>
If memory allocation fails for a hash entry, that specific file entry is skipped but processing continues with remaining entries.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="structTapeFileHeader.html"title="Header for a tape file metadata block containing file layout information.">TapeFileHeader</a> for the block header structure </dd>
<dd>
<aclass="el"href="structTapeFileEntry.html"title="Describes a single logical file on a tape medium.">TapeFileEntry</a> for individual file entry structure </dd>
<dd>
<aclass="el"href="context_8h.html#a5ba965cb003bc2d68a9f9e1c11225494">tapeFileHashEntry</a> for the hash table entry structure </dd>
<dd>
process_tape_partition_block() for partition metadata processing </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l00126">126</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<p>Processes a tape partition metadata block from the image stream. </p>
<p>Reads and parses a TapePartitionBlock from the Aaru image, validates its integrity, and populates the context's tape partition hash table with partition layout information. Each tape partition entry defines a physical division of the tape medium by specifying its partition number and block range (FirstBlock to LastBlock inclusive).</p>
<p>The function performs the following operations:</p><oltype="1">
<li>Seeks to the block position indicated by the index entry</li>
<li>Reads and validates the <aclass="el"href="structTapePartitionHeader.html"title="Header for a tape partition metadata block containing partition layout information.">TapePartitionHeader</a> structure</li>
<li>Allocates and reads the array of <aclass="el"href="structTapePartitionEntry.html"title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> structures</li>
<li>Validates data integrity using CRC64-ECMA checksum</li>
<li>Inserts each partition entry into the context's UTHASH table with partition number as key</li>
<li>Updates image size statistics</li>
</ol>
<p><b>Partition Identification:</b> Each tape partition is uniquely identified by its partition number (0-255). This number serves as the hash table key for fast lookup operations. Most tapes have a single partition (partition 0), but multi-partition formats like LTO, DLT, and AIT support multiple partitions with independent block address spaces.</p>
<p><b>Hash Table Management:</b> The function uses HASH_REPLACE to insert entries, which automatically:</p><ul>
<li>Adds new entries if the partition number doesn't exist</li>
<li>Replaces existing entries if the partition number is found (freeing the old entry) This ensures that duplicate partition definitions are properly handled by keeping only the most recent definition.</li>
</ul>
<p><b>Error Handling:</b> The function treats most errors as non-fatal and continues processing:</p><ul>
<li>Invalid context or stream: Returns immediately (FATAL log)</li>
<divclass="ttc"id="astructTapePartitionEntry_html"><divclass="ttname"><ahref="structTapePartitionEntry.html">TapePartitionEntry</a></div><divclass="ttdoc">Describes a single physical partition on a tape medium.</div><divclass="ttdef"><b>Definition</b><ahref="tape_8h_source.html#l00319">tape.h:320</a></div></div>
</div><!-- fragment --><p><b>CRC64 Validation:</b> The CRC64 checksum in the header is computed over the entire array of <aclass="el"href="structTapePartitionEntry.html"title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> structures (excluding the header itself). This provides integrity verification to detect corruption in the partition table.</p>
<p><b>Partition Block Ranges:</b> Each partition defines a block address space:</p><ul>
<li>FirstBlock: Starting block address (often 0, but format-dependent)</li>
<p>Block addresses are local to each partition. Different partitions may have overlapping logical block numbers (e.g., both partition 0 and partition 1 can have blocks numbered 0-1000).</p>
<p><b>Memory Management:</b></p><ul>
<li>Allocates a temporary buffer to read all partition entries</li>
<li>Allocates individual hash table entries for each partition</li>
<li>Frees the temporary buffer before returning</li>
<li>Hash table entries remain in context until cleanup</li>
</ul>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ctx</td><td>Pointer to the aaruformat context. Must not be NULL. The context must have a valid imageStream open for reading. The ctx->tapePartitions hash table will be populated with partition entries. The ctx->imageInfo.ImageSize will be updated with the block size.</td></tr>
<tr><tdclass="paramname">entry</td><td>Pointer to the index entry describing the tape partition block. Must not be NULL. The entry->offset field indicates the file position where the <aclass="el"href="structTapePartitionHeader.html"title="Header for a tape partition metadata block containing partition layout information.">TapePartitionHeader</a> begins.</td></tr>
</table>
</dd>
</dl>
<dlclass="section note"><dt>Note</dt><dd>This function does not return a status code. All errors are handled internally with appropriate logging and the function returns early on fatal errors.</dd>
<dd>
The tape partition hash table (ctx->tapePartitions) must be initialized to NULL before the first call to this function. UTHASH will manage the table automatically as entries are added.</dd>
<dd>
Partitions are ordered in the hash table by their partition number, not by insertion order. To iterate partitions in numerical order, use HASH_SORT with an appropriate comparison function.</dd>
<dd>
The function updates ctx->imageInfo.ImageSize by adding the size of all partition entries (entries × sizeof(TapePartitionEntry)). This contributes to the total reported image size but does not include the header size.</dd>
<dd>
The partition metadata is essential for correctly interpreting tape file locations, as files reference partition numbers in their definitions. Without partition metadata, tape file block ranges may be ambiguous.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The context and imageStream must be valid. Passing NULL pointers will result in immediate return with a FATAL log message.</dd>
<dd>
If the CRC64 checksum validation fails, all entries in the block are discarded. The function does not attempt partial recovery.</dd>
<dd>
If memory allocation fails for a hash entry, that specific partition entry is skipped but processing continues with remaining entries.</dd>
<dd>
If multiple partition entries have the same Number field, only the last occurrence is retained. This should not occur in valid images.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="structTapePartitionHeader.html"title="Header for a tape partition metadata block containing partition layout information.">TapePartitionHeader</a> for the block header structure </dd>
<dd>
<aclass="el"href="structTapePartitionEntry.html"title="Describes a single physical partition on a tape medium.">TapePartitionEntry</a> for individual partition entry structure </dd>
<dd>
<aclass="el"href="structTapePartitionHashEntry.html">TapePartitionHashEntry</a> for the hash table entry structure </dd>
<dd>
<aclass="el"href="#a829bbac3c17b60efd8f93188a8de8278"title="Processes a tape file metadata block from the image stream.">process_tape_files_block()</a> for tape file metadata processing </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="tape_8c_source.html#l00346">346</a> of file <aclass="el"href="tape_8c_source.html">tape.c</a>.</p>
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.14.0 </li>
