aaru-dps/libaaruformat
1
0
Fork 0
mirror of https://github.com/aaru-dps/libaaruformat.git synced 2025-12-16 19:24:40 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
b600857b2ea882ad4bef36b0c96de499cd9fd4e5
libaaruformat/docs/html/index__v3_8c.html

466 lines
30 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.14.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libaaruformat: src/index/index_v3.c File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">libaaruformat<span id="projectnumber">&#160;1.0</span>
</div>
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.14.0 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(function(){initNavTree('index__v3_8c.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="headertitle"><div class="title">index_v3.c File Reference</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><code>#include &lt;limits.h&gt;</code><br />
<code>#include &lt;stdbool.h&gt;</code><br />
<code>#include &lt;stdint.h&gt;</code><br />
<code>#include &lt;stdio.h&gt;</code><br />
<code>#include &lt;stdlib.h&gt;</code><br />
<code>#include &quot;<a class="el" href="aaruformat_8h_source.html">aaruformat.h</a>&quot;</code><br />
<code>#include &quot;<a class="el" href="internal_8h_source.html">internal.h</a>&quot;</code><br />
<code>#include &quot;<a class="el" href="log_8h_source.html">log.h</a>&quot;</code><br />
<code>#include &quot;utarray.h&quot;</code><br />
</div>
<p><a href="index__v3_8c_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ac85ad03ba0f06b8799d7fe056b87a18e" id="r_ac85ad03ba0f06b8799d7fe056b87a18e"><td class="memItemLeft" align="right" valign="top">static bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ac85ad03ba0f06b8799d7fe056b87a18e">add_subindex_entries</a> (<a class="el" href="structaaruformat__context.html">aaruformat_context</a> *ctx, UT_array *index_entries, const <a class="el" href="structIndexEntry.html">IndexEntry</a> *subindex_entry)</td></tr>
<tr class="memdesc:ac85ad03ba0f06b8799d7fe056b87a18e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Adds entries from a subindex block (version 3) to the main index entries array. <br /></td></tr>
<tr class="memitem:aff88fae9938d5f56318bfd7a455d5e94" id="r_aff88fae9938d5f56318bfd7a455d5e94"><td class="memItemLeft" align="right" valign="top">UT_array *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#aff88fae9938d5f56318bfd7a455d5e94">process_index_v3</a> (<a class="el" href="structaaruformat__context.html">aaruformat_context</a> *ctx)</td></tr>
<tr class="memdesc:aff88fae9938d5f56318bfd7a455d5e94"><td class="mdescLeft">&#160;</td><td class="mdescRight">Processes an index block (version 3) from the image stream. <br /></td></tr>
<tr class="memitem:ad7ed9250463c320c7bc8d83689bcfefb" id="r_ad7ed9250463c320c7bc8d83689bcfefb"><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ad7ed9250463c320c7bc8d83689bcfefb">verify_index_v3</a> (<a class="el" href="structaaruformat__context.html">aaruformat_context</a> *ctx)</td></tr>
<tr class="memdesc:ad7ed9250463c320c7bc8d83689bcfefb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Verifies the integrity of an index block (version 3) in the image stream. <br /></td></tr>
</table>
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
<a id="ac85ad03ba0f06b8799d7fe056b87a18e" name="ac85ad03ba0f06b8799d7fe056b87a18e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac85ad03ba0f06b8799d7fe056b87a18e">&#9670;&#160;</a></span>add_subindex_entries()</h2>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">bool add_subindex_entries </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structaaruformat__context.html">aaruformat_context</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">UT_array *</td> <td class="paramname"><span class="paramname"><em>index_entries</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="structIndexEntry.html">IndexEntry</a> *</td> <td class="paramname"><span class="paramname"><em>subindex_entry</em></span>&#160;)</td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel static">static</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Adds entries from a subindex block (version 3) to the main index entries array. </p>
<p>Recursively reads subindex blocks and appends their entries to the main index entries array. This function is a critical component of the hierarchical index system in AaruFormat version 3, enabling scalable index organization for large image files. It performs recursive traversal of subindex structures, flattening the hierarchy into a single array while maintaining entry order and handling nested subindex references.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ctx</td><td>Pointer to the aaruformat context containing the image stream. </td></tr>
<tr><td class="paramname">index_entries</td><td>Pointer to the UT_array of main index entries to append to. </td></tr>
<tr><td class="paramname">subindex_entry</td><td>Pointer to the <a class="el" href="structIndexEntry.html" title="Single index entry describing a block&#39;s type, (optional) data classification, and file offset.">IndexEntry</a> describing the subindex location and metadata.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns true when entries are appended successfully, false when an error occurs.</dd></dl>
<dl class="section note"><dt>Note</dt><dd>Function Behavior:<ul>
<li>Successfully appends subindex entries when all parameters are valid and file I/O succeeds</li>
<li>Recursively processes nested subindexes when entries have blockType == IndexBlock3</li>
<li>Returns false without modifying the array when validation fails or errors occur</li>
<li>Does not perform error reporting beyond logging (errors are handled gracefully)</li>
</ul>
</dd>
<dd>
Success Conditions - Entries are added when:<ul>
<li>All input parameters (ctx, index_entries, subindex_entry) are non-NULL</li>
<li>The image stream is valid and accessible</li>
<li>File positioning succeeds to subindex_entry-&gt;offset</li>
<li>The subindex header is successfully read from the image stream</li>
<li>The subindex identifier matches IndexBlock3 (correct format)</li>
<li>All entries in the subindex are successfully read and processed</li>
<li>Recursive calls for nested subindexes complete successfully</li>
</ul>
</dd>
<dd>
Failure Conditions - Function returns false when:<ul>
<li>Any input parameter is NULL (ctx, index_entries, or subindex_entry)</li>
<li>The image stream (ctx-&gt;imageStream) is NULL or invalid</li>
<li>File I/O errors prevent reading the subindex header or entries</li>
<li>The subindex identifier doesn't match IndexBlock3 (format mismatch or corruption)</li>
<li>Memory operations fail during UT_array manipulation</li>
</ul>
</dd>
<dd>
Recursive Processing:<ul>
<li>When an entry has blockType == IndexBlock3, it indicates another subindex</li>
<li>The function recursively calls itself to process nested subindexes</li>
<li>Supports arbitrary nesting depth limited only by stack space and file structure</li>
<li>All entries are flattened into the main index_entries array regardless of nesting level</li>
</ul>
</dd>
<dd>
Memory and Performance:<ul>
<li>Memory usage scales with the total number of entries across all processed subindexes</li>
<li>File I/O is performed for each subindex block accessed</li>
<li>Processing time increases with the depth and breadth of subindex hierarchies</li>
<li>No internal memory allocation - uses existing UT_array structure</li>
</ul>
</dd>
<dd>
Error Handling:<ul>
<li>Designed for graceful degradation - errors don't propagate to callers</li>
<li>Invalid subindexes are skipped without affecting other processing</li>
<li>Partial success is possible when some subindexes fail but others succeed</li>
<li>Logging provides visibility into processing failures for debugging</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>This function modifies the index_entries array by appending new entries. Ensure the array has sufficient capacity and is properly initialized.</dd>
<dd>
Recursive processing can cause significant stack usage for deeply nested subindex structures. Very deep hierarchies may cause stack overflow.</dd>
<dd>
The function assumes subindex_entry-&gt;offset points to a valid subindex block. Invalid offsets will cause file access errors but are handled gracefully.</dd>
<dd>
No validation is performed on individual <a class="el" href="structIndexEntry.html" title="Single index entry describing a block&#39;s type, (optional) data classification, and file offset.">IndexEntry</a> contents - only structural validation of subindex headers is done. </dd></dl>
<p class="definition">Definition at line <a class="el" href="index__v3_8c_source.html#l00247">247</a> of file <a class="el" href="index__v3_8c_source.html">index_v3.c</a>.</p>
<p class="reference">References <a class="el" href="index__v3_8c_source.html#l00247">add_subindex_entries()</a>, <a class="el" href="index_8h_source.html#l00110">IndexEntry::blockType</a>, <a class="el" href="index_8h_source.html#l00095">IndexHeader3::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="index_8h_source.html#l00094">IndexHeader3::identifier</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="enums_8h_source.html#l00147">IndexBlock3</a>, <a class="el" href="index_8h_source.html#l00112">IndexEntry::offset</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
<p class="reference">Referenced by <a class="el" href="index__v3_8c_source.html#l00247">add_subindex_entries()</a>, and <a class="el" href="index__v3_8c_source.html#l00098">process_index_v3()</a>.</p>
</div>
</div>
<a id="aff88fae9938d5f56318bfd7a455d5e94" name="aff88fae9938d5f56318bfd7a455d5e94"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aff88fae9938d5f56318bfd7a455d5e94">&#9670;&#160;</a></span>process_index_v3()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">UT_array * process_index_v3 </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structaaruformat__context.html">aaruformat_context</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Processes an index block (version 3) from the image stream. </p>
<p>Reads and parses an index block (version 3) from the image, returning an array of index entries. This function handles the advanced index format used in current AaruFormat versions, supporting hierarchical subindex structures for improved scalability. It reads the <a class="el" href="structIndexHeader3.html" title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a> structure followed by index entries, recursively processing any subindex blocks encountered to create a flattened array of all index entries.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ctx</td><td>Pointer to the aaruformat context containing the image stream and header information.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following values: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">UT_array*</td><td>Successfully processed the index block and all subindexes. This is returned when:<ul>
<li>The context and image stream are valid</li>
<li>The index header is successfully read from the position specified in ctx-&gt;header.indexOffset</li>
<li>The index identifier matches IndexBlock3 (version 3 format identifier)</li>
<li>All index entries are successfully read and stored in the UT_array</li>
<li>Any subindex blocks (IndexBlock3 entries) are recursively processed via <a class="el" href="#ac85ad03ba0f06b8799d7fe056b87a18e" title="Adds entries from a subindex block (version 3) to the main index entries array.">add_subindex_entries()</a></li>
<li>Memory allocation for the index entries array succeeds</li>
<li>The returned array contains all index entries from the main index and all subindexes</li>
</ul>
</td></tr>
<tr><td class="paramname">NULL</td><td>Index processing failed. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The image stream (ctx-&gt;imageStream) is NULL or invalid</li>
<li>Cannot read the <a class="el" href="structIndexHeader3.html" title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a> structure from the image stream</li>
<li>The index identifier doesn't match IndexBlock3 (incorrect format or corruption)</li>
<li>Memory allocation fails for the UT_array structure</li>
<li>File I/O errors occur while reading index entries</li>
<li>Recursive subindex processing fails (errors in <a class="el" href="#ac85ad03ba0f06b8799d7fe056b87a18e" title="Adds entries from a subindex block (version 3) to the main index entries array.">add_subindex_entries()</a>)</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Index Structure (Version 3):<ul>
<li><a class="el" href="structIndexHeader3.html" title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a>: Contains identifier (IndexBlock3), entry count, and advanced metadata</li>
<li><a class="el" href="structIndexEntry.html" title="Single index entry describing a block&#39;s type, (optional) data classification, and file offset.">IndexEntry</a> array: May contain regular entries and subindex references (IndexBlock3 type)</li>
<li>Hierarchical support: Subindex entries are recursively processed to flatten the structure</li>
<li>No CRC validation is performed during processing (use verify_index_v3 for validation)</li>
<li>Supports scalable index organization for large image files</li>
</ul>
</dd>
<dd>
Subindex Processing:<ul>
<li>When an <a class="el" href="structIndexEntry.html" title="Single index entry describing a block&#39;s type, (optional) data classification, and file offset.">IndexEntry</a> has blockType == IndexBlock3, it references a subindex</li>
<li>Subindexes are recursively processed using <a class="el" href="#ac85ad03ba0f06b8799d7fe056b87a18e" title="Adds entries from a subindex block (version 3) to the main index entries array.">add_subindex_entries()</a></li>
<li>All entries from subindexes are flattened into the main index entries array</li>
<li>Supports arbitrary nesting depth of subindexes</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>Returns a newly allocated UT_array that must be freed by the caller using utarray_free()</li>
<li>On error, any partially allocated memory is cleaned up before returning NULL</li>
<li>Each <a class="el" href="structIndexEntry.html" title="Single index entry describing a block&#39;s type, (optional) data classification, and file offset.">IndexEntry</a> is copied into the array (no reference to original stream data)</li>
<li>Memory usage scales with total entries across all subindexes</li>
</ul>
</dd>
<dd>
Version Compatibility:<ul>
<li>Supports only IndexBlock3 format (not IndexBlock or IndexBlock2)</li>
<li>Compatible with current generation AaruFormat image files</li>
<li>Backward compatible with images that don't use subindexes</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The caller is responsible for freeing the returned UT_array using utarray_free(). Failure to free the array will result in memory leaks.</dd>
<dd>
This function does not validate the CRC integrity of the index data. Use <a class="el" href="#ad7ed9250463c320c7bc8d83689bcfefb" title="Verifies the integrity of an index block (version 3) in the image stream.">verify_index_v3()</a> to ensure index integrity before processing.</dd>
<dd>
Recursive subindex processing may cause significant memory usage and processing time for images with deeply nested or numerous subindexes.</dd>
<dd>
The function assumes ctx-&gt;header.indexOffset points to a valid index block. Invalid offsets may cause file access errors or reading incorrect data. </dd></dl>
<p class="definition">Definition at line <a class="el" href="index__v3_8c_source.html#l00098">98</a> of file <a class="el" href="index__v3_8c_source.html">index_v3.c</a>.</p>
<p class="reference">References <a class="el" href="index__v3_8c_source.html#l00247">add_subindex_entries()</a>, <a class="el" href="index_8h_source.html#l00110">IndexEntry::blockType</a>, <a class="el" href="index_8h_source.html#l00095">IndexHeader3::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00175">aaruformat_context::header</a>, <a class="el" href="index_8h_source.html#l00094">IndexHeader3::identifier</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="enums_8h_source.html#l00147">IndexBlock3</a>, <a class="el" href="header_8h_source.html#l00115">AaruHeaderV2::indexOffset</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
<p class="reference">Referenced by <a class="el" href="open_8c_source.html#l00223">aaruf_open()</a>, and <a class="el" href="verify_8c_source.html#l00130">aaruf_verify_image()</a>.</p>
</div>
</div>
<a id="ad7ed9250463c320c7bc8d83689bcfefb" name="ad7ed9250463c320c7bc8d83689bcfefb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad7ed9250463c320c7bc8d83689bcfefb">&#9670;&#160;</a></span>verify_index_v3()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t verify_index_v3 </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structaaruformat__context.html">aaruformat_context</a> *</td> <td class="paramname"><span class="paramname"><em>ctx</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Verifies the integrity of an index block (version 3) in the image stream. </p>
<p>Checks the CRC64 of the index block and all subindexes without decompressing them. This function performs comprehensive validation of the advanced version 3 index structure including header validation, data integrity verification, and version-specific CRC calculation. Note that this function validates only the main index block's CRC and does not recursively validate subindex CRCs, focusing on the primary index structure integrity.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ctx</td><td>Pointer to the aaruformat context containing image stream and header information.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns one of the following status codes: </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">AARUF_STATUS_OK</td><td>(0) Successfully verified index integrity. This is returned when:<ul>
<li>The context and image stream are valid</li>
<li>The index header is successfully read from ctx-&gt;header.indexOffset</li>
<li>The index identifier matches IndexBlock3 (version 3 format)</li>
<li>Memory allocation for index entries succeeds</li>
<li>All index entries are successfully read from the image stream</li>
<li>CRC64 calculation completes successfully with version-specific endianness handling</li>
<li>The calculated CRC64 matches the expected CRC64 in the index header</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) Invalid context or stream. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The image stream (ctx-&gt;imageStream) is NULL or invalid</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_HEADER</td><td>(-6) Index header reading failed. This occurs when:<ul>
<li>Cannot read the complete <a class="el" href="structIndexHeader3.html" title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a> structure from the image stream</li>
<li>File I/O errors prevent accessing the header at ctx-&gt;header.indexOffset</li>
<li>Insufficient data available at the specified index offset</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_INDEX</td><td>(-19) Index format or data access errors. This occurs when:<ul>
<li>The index identifier doesn't match IndexBlock3 (wrong format or corruption)</li>
<li>Cannot read all index entries from the image stream</li>
<li>File I/O errors during index entry reading</li>
<li>Index structure is corrupted or truncated</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-9) Memory allocation failed. This occurs when:<ul>
<li>Cannot allocate memory for the index entries array</li>
<li>System memory exhaustion prevents loading index data for verification</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_INVALID_BLOCK_CRC</td><td>(-18) CRC64 validation failed. This occurs when:<ul>
<li>The calculated CRC64 doesn't match the expected CRC64 in the index header</li>
<li>Index data corruption is detected</li>
<li>Data integrity verification fails indicating potential file damage</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>CRC64 Validation Process:<ul>
<li>Reads all main index entries into memory for CRC calculation</li>
<li>Calculates CRC64 over the complete main index entries array</li>
<li>Applies version-specific endianness conversion for compatibility</li>
<li>For imageMajorVersion &lt;= AARUF_VERSION_V1: Uses <a class="el" href="endian_8h.html#a0c0b427a2547aa727e2c5262a174e26b">bswap_64()</a> for byte order correction</li>
<li>Compares calculated CRC64 with the value stored in the <a class="el" href="structIndexHeader3.html" title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a></li>
</ul>
</dd>
<dd>
Version 3 Specific Features:<ul>
<li>Uses <a class="el" href="structIndexHeader3.html" title="Index header (version 3) adding hierarchical chaining (identifier == IndexBlock3).">IndexHeader3</a> structure with hierarchical subindex support</li>
<li>Maintains compatibility with legacy endianness handling</li>
<li>Supports advanced index entry organization with subindex references</li>
<li>Only validates the main index block CRC - subindex CRCs are not recursively checked</li>
</ul>
</dd>
<dd>
Validation Scope:<ul>
<li>Validates main index header structure and identifier</li>
<li>Verifies data integrity of the primary index entries through CRC64 calculation</li>
<li>Does not validate individual <a class="el" href="structIndexEntry.html" title="Single index entry describing a block&#39;s type, (optional) data classification, and file offset.">IndexEntry</a> contents or block references</li>
<li>Does not check for logical consistency of referenced blocks</li>
<li>Does not recursively validate subindex blocks (unlike hierarchical processing)</li>
</ul>
</dd>
<dd>
Memory Management:<ul>
<li>Allocates temporary memory for index entries during verification</li>
<li>Automatically frees allocated memory on both success and error conditions</li>
<li>Memory usage is proportional to the number of entries in the main index only</li>
</ul>
</dd>
<dd>
Subindex Validation Limitation:<ul>
<li>This function does not recursively validate subindex CRCs</li>
<li>Each subindex block contains its own CRC that would need separate validation</li>
<li>For complete integrity verification, subindex blocks should be validated individually</li>
<li>The main index CRC only covers the primary index entries, not the subindex content</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>This function reads only the main index into memory for CRC calculation. Subindex blocks are not loaded or validated by this function.</dd>
<dd>
The function assumes ctx-&gt;header.indexOffset points to a valid index location. Invalid offsets will cause file access errors or incorrect validation.</dd>
<dd>
CRC validation failure indicates potential data corruption in the main index and may suggest the image file is damaged or has been modified outside of library control.</dd>
<dd>
For complete integrity verification of hierarchical indexes, additional validation of subindex blocks may be required beyond this function's scope. </dd></dl>
<p class="definition">Definition at line <a class="el" href="index__v3_8c_source.html#l00408">408</a> of file <a class="el" href="index__v3_8c_source.html">index_v3.c</a>.</p>
<p class="reference">References <a class="el" href="crc64_8c_source.html#l00141">aaruf_crc64_final()</a>, <a class="el" href="crc64_8c_source.html#l00155">aaruf_crc64_free()</a>, <a class="el" href="crc64_8c_source.html#l00032">aaruf_crc64_init()</a>, <a class="el" href="crc64_8c_source.html#l00055">aaruf_crc64_update()</a>, <a class="el" href="errors_8h_source.html#l00045">AARUF_ERROR_CANNOT_READ_HEADER</a>, <a class="el" href="errors_8h_source.html#l00043">AARUF_ERROR_CANNOT_READ_INDEX</a>, <a class="el" href="errors_8h_source.html#l00057">AARUF_ERROR_INVALID_BLOCK_CRC</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00048">AARUF_ERROR_NOT_ENOUGH_MEMORY</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="consts_8h_source.html#l00071">AARUF_VERSION_V1</a>, <a class="el" href="endian_8h_source.html#l00081">bswap_64</a>, <a class="el" href="index_8h_source.html#l00096">IndexHeader3::crc64</a>, <a class="el" href="index_8h_source.html#l00095">IndexHeader3::entries</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00175">aaruformat_context::header</a>, <a class="el" href="index_8h_source.html#l00094">IndexHeader3::identifier</a>, <a class="el" href="header_8h_source.html#l00110">AaruHeaderV2::imageMajorVersion</a>, <a class="el" href="context_8h_source.html#l00176">aaruformat_context::imageStream</a>, <a class="el" href="enums_8h_source.html#l00147">IndexBlock3</a>, <a class="el" href="header_8h_source.html#l00115">AaruHeaderV2::indexOffset</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
<p class="reference">Referenced by <a class="el" href="verify_8c_source.html#l00130">aaruf_verify_image()</a>.</p>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a href="dir_68267d1309a1af8e8297ef4c3efbcdba.html">src</a></li><li class="navelem"><a href="dir_19ac67bde96fa7098d9c89fb8e36db69.html">index</a></li><li class="navelem"><a href="index__v3_8c.html">index_v3.c</a></li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0 </li>
</ul>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink