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
03c091fdeefdcf6b1a6093294609c4693b5138ef
libaaruformat/docs/html/verify_8c.html

314 lines
19 KiB
HTML
Raw Normal View History

Add doxygen documentation
2025-10-11 01:35:43 +01:00
<!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/verify.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('verify_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">verify.c File Reference</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><code>#include &lt;<a class="el" href="aaruformat_8h_source.html">aaruformat.h</a>&gt;</code><br />
<code>#include &lt;inttypes.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="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="verify_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-define-members" class="groupheader"><a id="define-members" name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:a11acb6252d1adf9fab3786ed6820d911" id="r_a11acb6252d1adf9fab3786ed6820d911"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a11acb6252d1adf9fab3786ed6820d911">VERIFY_SIZE</a>&#160;&#160;&#160;1048576</td></tr>
</table><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:a9af5ef946af3841757b56af39cb9e60d" id="r_a9af5ef946af3841757b56af39cb9e60d"><td class="memItemLeft" align="right" valign="top">static int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a9af5ef946af3841757b56af39cb9e60d">update_crc64_from_stream</a> (FILE *stream, const uint64_t total_length, void *buffer, size_t buffer_size, <a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *crc_ctx, const char *label)</td></tr>
<tr class="memitem:a8cbf4d8059c4b36e8ab5e18fec057b52" id="r_a8cbf4d8059c4b36e8ab5e18fec057b52"><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a8cbf4d8059c4b36e8ab5e18fec057b52">aaruf_verify_image</a> (void *context)</td></tr>
<tr class="memdesc:a8cbf4d8059c4b36e8ab5e18fec057b52"><td class="mdescLeft">&#160;</td><td class="mdescRight">Verifies the integrity of an AaruFormat image file. <br /></td></tr>
</table>
<a name="doc-define-members" id="doc-define-members"></a><h2 id="header-doc-define-members" class="groupheader">Macro Definition Documentation</h2>
<a id="a11acb6252d1adf9fab3786ed6820d911" name="a11acb6252d1adf9fab3786ed6820d911"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a11acb6252d1adf9fab3786ed6820d911">&#9670;&#160;</a></span>VERIFY_SIZE</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define VERIFY_SIZE&#160;&#160;&#160;1048576</td>
</tr>
</table>
</div><div class="memdoc">
<p class="definition">Definition at line <a class="el" href="verify_8c_source.html#l00028">28</a> of file <a class="el" href="verify_8c_source.html">verify.c</a>.</p>
<p class="reference">Referenced by <a class="el" href="verify_8c_source.html#l00130">aaruf_verify_image()</a>.</p>
</div>
</div>
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
<a id="a8cbf4d8059c4b36e8ab5e18fec057b52" name="a8cbf4d8059c4b36e8ab5e18fec057b52"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8cbf4d8059c4b36e8ab5e18fec057b52">&#9670;&#160;</a></span>aaruf_verify_image()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t aaruf_verify_image </td>
<td>(</td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>context</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Verifies the integrity of an AaruFormat image file. </p>
<p>Checks the integrity of all blocks and deduplication tables in the image by validating CRC64 checksums for each indexed block. This function performs comprehensive verification of data blocks, DDT v1 and v2 tables, tracks blocks, and other structural components. It reads blocks in chunks to optimize memory usage during verification and supports version-specific CRC endianness handling.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">context</td><td>Pointer to the aaruformat context.</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 image integrity. This is returned when:<ul>
<li>All indexed blocks are successfully read and processed</li>
<li>All CRC64 checksums match their expected values</li>
<li>Index verification passes for the detected index version</li>
<li>All block headers are readable and valid</li>
<li>Memory allocation for verification buffer succeeds</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_NOT_AARUFORMAT</td><td>(-1) The context is invalid. This occurs when:<ul>
<li>The context parameter is NULL</li>
<li>The context magic number doesn't match AARU_MAGIC (invalid context type)</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_HEADER</td><td>(-6) Failed to read critical headers. This occurs when:<ul>
<li>Cannot read the index signature from the image stream</li>
<li>File I/O errors prevent reading header structures</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_INDEX</td><td>(-4) Index processing or validation failed. This occurs when:<ul>
<li>Index signature is not a recognized type (IndexBlock, IndexBlock2, or IndexBlock3)</li>
<li>Index verification functions return error codes</li>
<li>Index processing functions return NULL (corrupted or invalid index)</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 VERIFY_SIZE (1MB) buffer for reading block data during verification</li>
<li>System is out of available memory for verification operations</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-7) Block reading failed. This occurs when:<ul>
<li>Cannot read block headers (DataBlock, DeDuplicationTable, DeDuplicationTable2, TracksBlock)</li>
<li>File I/O errors prevent reading block structure data</li>
<li>CRC64 context initialization fails (internal error)</li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_INVALID_BLOCK_CRC</td><td>(-18) CRC verification failed. This occurs when:<ul>
<li>Calculated CRC64 doesn't match the expected CRC64 in block headers</li>
<li>Data corruption is detected in any verified block</li>
<li>This applies to DataBlock, DeDuplicationTable, DeDuplicationTable2, and TracksBlock types</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Verification Process:<ul>
<li>Reads blocks in VERIFY_SIZE (1MB) chunks to optimize memory usage</li>
<li>Supports version-specific CRC64 endianness (v1 uses byte-swapped CRC64)</li>
<li>Verifies only blocks that have CRC checksums (skips blocks without checksums)</li>
<li>Unknown block types are logged but don't cause verification failure</li>
</ul>
</dd>
<dd>
Block Types Verified:<ul>
<li>DataBlock: Verifies compressed data CRC64 against block header</li>
<li>DeDuplicationTable (v1): Verifies DDT data CRC64 with version-specific endianness</li>
<li>DeDuplicationTable2 (v2): Verifies DDT data CRC64 (no endianness conversion)</li>
<li>TracksBlock: Verifies track entries CRC64 with version-specific endianness</li>
<li>Other block types are ignored during verification</li>
</ul>
</dd>
<dd>
Performance Considerations:<ul>
<li>Uses chunked reading to minimize memory footprint during verification</li>
<li>Processes blocks sequentially to maintain good disk access patterns</li>
<li>CRC64 contexts are created and destroyed for each block to prevent memory leaks</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>This function performs read-only verification and does not modify the image. It requires the image to be properly opened with a valid context.</dd>
<dd>
Verification failure indicates data corruption or tampering. Images that fail verification should not be trusted for data recovery operations.</dd>
<dd>
The function allocates a 1MB buffer for verification. Ensure sufficient memory is available before calling this function on resource-constrained systems. </dd></dl>
<p class="definition">Definition at line <a class="el" href="verify_8c_source.html#l00130">130</a> of file <a class="el" href="verify_8c_source.html">verify.c</a>.</p>
Update doxygen documentation.
2025-10-11 12:43:39 +01:00
<p class="reference">References <a class="el" href="decls_8h_source.html#l00045">AARU_CALL</a>, <a class="el" href="decls_8h_source.html#l00054">AARU_EXPORT</a>, <a class="el" href="consts_8h_source.html#l00064">AARU_MAGIC</a>, <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="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</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="index_8h_source.html#l00110">IndexEntry::blockType</a>, <a class="el" href="endian_8h_source.html#l00081">bswap_64</a>, <a class="el" href="data_8h_source.html#l00078">BlockHeader::cmpCrc64</a>, <a class="el" href="ddt_8h_source.html#l00161">DdtHeader2::cmpCrc64</a>, <a class="el" href="ddt_8h_source.html#l00074">DdtHeader::cmpCrc64</a>, <a class="el" href="data_8h_source.html#l00076">BlockHeader::cmpLength</a>, <a class="el" href="ddt_8h_source.html#l00159">DdtHeader2::cmpLength</a>, <a class="el" href="ddt_8h_source.html#l00072">DdtHeader::cmpLength</a>, <a class="el" href="optical_8h_source.html#l00065">TracksHeader::crc64</a>, <a class="el" href="enums_8h_source.html#l00141">DataBlock</a>, <a class="el" href="enums_8h_source.html#l00142">DeDuplicationTable</a>, <a class="el" href="enums_8h_source.html#l00143">DeDuplicationTable2</a>, <a class="el" href="optical_8h_source.html#l00064">TracksHeader::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="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#l00145">IndexBlock</a>, <a class="el" href="enums_8h_source.html#l00146">IndexBlock2</a>, <a class="el" href="enums_8h_source.html#l00147">IndexBlock3</a>, <a class="el" href="header_8h_source.html#l00115">AaruHeaderV2::indexOffset</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="index_8h_source.html#l00112">IndexEntry::offset</a>, <a class="el" href="index__v1_8c_source.html#l00079">process_index_v1()</a>, <a class="el" href="index__v2_8c_source.html#l00081">process_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00098">process_index_v3()</a>, <a class="el" href="log_8h_source.html#l00025">TRACE</a>, <a class="el" href="enums_8h_source.html#l00150">TracksBlock</a>, <a class="el" href="verify_8c_source.html#l00030">update_crc64_from_stream()</a>, <a class="el" href="index__v1_8c_source.html#l00225">verify_index_v1()</a>, <a class="el" href="index__v2_8c_source.html#l00227">verify_index_v2()</a>, <a class="el" href="index__v3_8c_source.html#l00408">verify_index_v3()</a>, and <a class="el" href="verify_8c_source.html#l00028">VERIFY_SIZE</a>.</p>
Add doxygen documentation
2025-10-11 01:35:43 +01:00
</div>
</div>
<a id="a9af5ef946af3841757b56af39cb9e60d" name="a9af5ef946af3841757b56af39cb9e60d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a9af5ef946af3841757b56af39cb9e60d">&#9670;&#160;</a></span>update_crc64_from_stream()</h2>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">int32_t update_crc64_from_stream </td>
<td>(</td>
<td class="paramtype">FILE *</td> <td class="paramname"><span class="paramname"><em>stream</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const uint64_t</td> <td class="paramname"><span class="paramname"><em>total_length</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>buffer_size</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structcrc64__ctx.html">crc64_ctx</a> *</td> <td class="paramname"><span class="paramname"><em>crc_ctx</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>label</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 class="definition">Definition at line <a class="el" href="verify_8c_source.html#l00030">30</a> of file <a class="el" href="verify_8c_source.html">verify.c</a>.</p>
<p class="reference">References <a class="el" href="crc64_8c_source.html#l00055">aaruf_crc64_update()</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, and <a class="el" href="log_8h_source.html#l00040">FATAL</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="verify_8c.html">verify.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 Copy Permalink