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

Update documentation.

Browse Source
This commit is contained in:
Natalia Portillo
2025-10-21 14:23:35 +01:00
parent f53092c941
commit 55b688c522
109 changed files with 6592 additions and 6502 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/html/dump_8c.html
View File

@@ -127,16 +127,19 @@ Functions</h2></td></tr>
</tr>
</table>
</div><div class="memdoc">
<b>Value:</b><div class="fragment"><div class="line"> <span class="keywordflow">do</span> { \</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">size_t</span> field##_length = copy[e].entry.field##Length; \</div>
<div class="line"> if(field##_length &gt; 0) \</div>
<div class="line"> { \</div>
<div class="line"> if(field##_length &gt; length - pos) <span class="keywordflow">goto</span> invalid_data; \</div>
<div class="line"> copy[e].field = (uint8_t *)calloc(1, field##_length + 1); \</div>
<div class="line"> if(copy[e].field == NULL) <span class="keywordflow">goto</span> free_copy_and_error; \</div>
<div class="line"> memcpy(copy[e].field, data + pos, field##_length); \</div>
<div class="line"> pos += field##_length; \</div>
<div class="line"> } \</div>
<b>Value:</b><div class="fragment"><div class="line"> <span class="keywordflow">do</span> { \</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">size_t</span> field##_length = copy[e].entry.field##Length; \</div>
<div class="line"> if(field##_length &gt; 0) \</div>
<div class="line"> { \</div>
<div class="line"> if(field##_length &gt; length - pos) <span class="keywordflow">goto</span> invalid_data; \</div>
<div class="line"> <span class="comment">/* Allocate only field##_length bytes, since input is NUL-terminated */</span> \</div>
<div class="line"> copy[e].field = (uint8_t *)calloc(1, field##_length); \</div>
<div class="line"> if(copy[e].field == NULL) <span class="keywordflow">goto</span> free_copy_and_error; \</div>
<div class="line"> memcpy(copy[e].field, data + pos, field##_length); \</div>
<div class="line"> <span class="comment">/* Ensure NUL-termination in case input is malformed */</span> \</div>
<div class="line"> copy[e].field[field##_length - 1] = <span class="charliteral">&#39;\0&#39;</span>; \</div>
<div class="line"> pos += field##_length; \</div>
<div class="line"> } \</div>
<div class="line"> } <span class="keywordflow">while</span>(0)</div>
</div><!-- fragment -->
<p class="reference">Referenced by <a class="el" href="dump_8c_source.html#l00531">aaruf_set_dumphw()</a>.</p>
@@ -204,7 +207,7 @@ Functions</h2></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>
<li>The context was not properly initialized by <a class="el" href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context was not properly initialized by <a class="el" href="decls_8h.html#aefe69fae905b957bb4349ac59fad9bc7">aaruf_open()</a> or <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
<tr><td class="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-6) The dump hardware block is not present. This occurs when:<ul>
@@ -291,7 +294,7 @@ Use Cases:<ul>
<li>Correlating imaging artifacts with specific hardware/software combinations</li>
</ul>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>This function reads from the in-memory dump hardware data loaded during <a class="el" href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a>. It does not perform file I/O operations. The data is reconstructed from the parsed context structures into the on-disk binary format.</dd>
<dl class="section warning"><dt>Warning</dt><dd>This function reads from the in-memory dump hardware data loaded during <a class="el" href="decls_8h.html#aefe69fae905b957bb4349ac59fad9bc7">aaruf_open()</a>. It does not perform file I/O operations. The data is reconstructed from the parsed context structures into the on-disk binary format.</dd>
<dd>
The buffer must be valid and large enough to hold the entire dump hardware block. Passing a buffer smaller than required will result in AARUF_ERROR_BUFFER_TOO_SMALL.</dd>
<dd>
@@ -308,7 +311,7 @@ The function performs bounds checking during serialization. If calculated entry
<p class="definition">Definition at line <a class="el" href="dump_8c_source.html#l00186">186</a> of file <a class="el" href="dump_8c_source.html">dump.c</a>.</p>
<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#l00160">aaruf_crc64_data()</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="dump_8h_source.html#l00095">DumpHardwareHeader::crc64</a>, <a class="el" href="context_8h_source.html#l00212">aaruformat_context::dump_hardware_entries_with_data</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::dump_hardware_header</a>, <a class="el" href="enums_8h_source.html#l00156">DumpHardwareBlock</a>, <a class="el" href="dump_8h_source.html#l00093">DumpHardwareHeader::entries</a>, <a class="el" href="context_8h_source.html#l00315">DumpHardwareEntriesWithData::entry</a>, <a class="el" href="context_8h_source.html#l00316">DumpHardwareEntriesWithData::extents</a>, <a class="el" href="dump_8h_source.html#l00122">DumpHardwareEntry::extents</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00320">DumpHardwareEntriesWithData::firmware</a>, <a class="el" href="dump_8h_source.html#l00117">DumpHardwareEntry::firmwareLength</a>, <a class="el" href="dump_8h_source.html#l00092">DumpHardwareHeader::identifier</a>, <a class="el" href="dump_8h_source.html#l00094">DumpHardwareHeader::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00317">DumpHardwareEntriesWithData::manufacturer</a>, <a class="el" href="dump_8h_source.html#l00114">DumpHardwareEntry::manufacturerLength</a>, <a class="el" href="context_8h_source.html#l00318">DumpHardwareEntriesWithData::model</a>, <a class="el" href="dump_8h_source.html#l00115">DumpHardwareEntry::modelLength</a>, <a class="el" href="context_8h_source.html#l00319">DumpHardwareEntriesWithData::revision</a>, <a class="el" href="dump_8h_source.html#l00116">DumpHardwareEntry::revisionLength</a>, <a class="el" href="context_8h_source.html#l00321">DumpHardwareEntriesWithData::serial</a>, <a class="el" href="dump_8h_source.html#l00118">DumpHardwareEntry::serialLength</a>, <a class="el" href="context_8h_source.html#l00322">DumpHardwareEntriesWithData::softwareName</a>, <a class="el" href="dump_8h_source.html#l00119">DumpHardwareEntry::softwareNameLength</a>, <a class="el" href="context_8h_source.html#l00324">DumpHardwareEntriesWithData::softwareOperatingSystem</a>, <a class="el" href="dump_8h_source.html#l00121">DumpHardwareEntry::softwareOperatingSystemLength</a>, <a class="el" href="context_8h_source.html#l00323">DumpHardwareEntriesWithData::softwareVersion</a>, <a class="el" href="dump_8h_source.html#l00120">DumpHardwareEntry::softwareVersionLength</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
<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#l00160">aaruf_crc64_data()</a>, <a class="el" href="errors_8h_source.html#l00049">AARUF_ERROR_BUFFER_TOO_SMALL</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</a>, <a class="el" href="errors_8h_source.html#l00040">AARUF_ERROR_NOT_AARUFORMAT</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="dump_8h_source.html#l00095">DumpHardwareHeader::crc64</a>, <a class="el" href="context_8h_source.html#l00212">aaruformat_context::dump_hardware_entries_with_data</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::dump_hardware_header</a>, <a class="el" href="enums_8h_source.html#l00156">DumpHardwareBlock</a>, <a class="el" href="dump_8h_source.html#l00093">DumpHardwareHeader::entries</a>, <a class="el" href="context_8h_source.html#l00316">DumpHardwareEntriesWithData::entry</a>, <a class="el" href="context_8h_source.html#l00317">DumpHardwareEntriesWithData::extents</a>, <a class="el" href="dump_8h_source.html#l00122">DumpHardwareEntry::extents</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="context_8h_source.html#l00321">DumpHardwareEntriesWithData::firmware</a>, <a class="el" href="dump_8h_source.html#l00117">DumpHardwareEntry::firmwareLength</a>, <a class="el" href="dump_8h_source.html#l00092">DumpHardwareHeader::identifier</a>, <a class="el" href="dump_8h_source.html#l00094">DumpHardwareHeader::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, <a class="el" href="context_8h_source.html#l00318">DumpHardwareEntriesWithData::manufacturer</a>, <a class="el" href="dump_8h_source.html#l00114">DumpHardwareEntry::manufacturerLength</a>, <a class="el" href="context_8h_source.html#l00319">DumpHardwareEntriesWithData::model</a>, <a class="el" href="dump_8h_source.html#l00115">DumpHardwareEntry::modelLength</a>, <a class="el" href="context_8h_source.html#l00320">DumpHardwareEntriesWithData::revision</a>, <a class="el" href="dump_8h_source.html#l00116">DumpHardwareEntry::revisionLength</a>, <a class="el" href="context_8h_source.html#l00322">DumpHardwareEntriesWithData::serial</a>, <a class="el" href="dump_8h_source.html#l00118">DumpHardwareEntry::serialLength</a>, <a class="el" href="context_8h_source.html#l00323">DumpHardwareEntriesWithData::softwareName</a>, <a class="el" href="dump_8h_source.html#l00119">DumpHardwareEntry::softwareNameLength</a>, <a class="el" href="context_8h_source.html#l00325">DumpHardwareEntriesWithData::softwareOperatingSystem</a>, <a class="el" href="dump_8h_source.html#l00121">DumpHardwareEntry::softwareOperatingSystemLength</a>, <a class="el" href="context_8h_source.html#l00324">DumpHardwareEntriesWithData::softwareVersion</a>, <a class="el" href="dump_8h_source.html#l00120">DumpHardwareEntry::softwareVersionLength</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>
@@ -394,7 +397,7 @@ environments" – typically combinations of physical devices (drives, controller
</ul>
</td></tr>
<tr><td class="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <a class="el" href="decls_8h.html#afc4932cdc795ffb2ef3a33d5b8c57656" title="Opens an existing AaruFormat image file.">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The image was opened with <a class="el" href="decls_8h.html#aefe69fae905b957bb4349ac59fad9bc7">aaruf_open()</a> instead of <a class="el" href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013" title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li>The context's isWriting flag is false</li>
<li>Attempting to modify a read-only image</li>
</ul>
@@ -502,7 +505,7 @@ The function assumes the input buffer is properly formatted and packed according
<p class="definition">Definition at line <a class="el" href="dump_8c_source.html#l00531">531</a> of file <a class="el" href="dump_8c_source.html">dump.c</a>.</p>
<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#l00160">aaruf_crc64_data()</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="helpers_8c_source.html#l00459">compare_extents()</a>, <a class="el" href="#a6b41f4a00a255e6704583614ef33571f">COPY_STRING_FIELD</a>, <a class="el" href="dump_8h_source.html#l00095">DumpHardwareHeader::crc64</a>, <a class="el" href="context_8h_source.html#l00212">aaruformat_context::dump_hardware_entries_with_data</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::dump_hardware_header</a>, <a class="el" href="enums_8h_source.html#l00156">DumpHardwareBlock</a>, <a class="el" href="dump_8h_source.html#l00093">DumpHardwareHeader::entries</a>, <a class="el" href="context_8h_source.html#l00315">DumpHardwareEntriesWithData::entry</a>, <a class="el" href="context_8h_source.html#l00316">DumpHardwareEntriesWithData::extents</a>, <a class="el" href="dump_8h_source.html#l00122">DumpHardwareEntry::extents</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="dump_8c_source.html#l00026">free_dump_hardware_entries()</a>, <a class="el" href="dump_8h_source.html#l00092">DumpHardwareHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="dump_8h_source.html#l00094">DumpHardwareHeader::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
<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#l00160">aaruf_crc64_data()</a>, <a class="el" href="errors_8h_source.html#l00046">AARUF_ERROR_CANNOT_READ_BLOCK</a>, <a class="el" href="errors_8h_source.html#l00065">AARUF_ERROR_INCORRECT_DATA_SIZE</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#l00061">AARUF_READ_ONLY</a>, <a class="el" href="errors_8h_source.html#l00075">AARUF_STATUS_OK</a>, <a class="el" href="helpers_8c_source.html#l00459">compare_extents()</a>, <a class="el" href="#a6b41f4a00a255e6704583614ef33571f">COPY_STRING_FIELD</a>, <a class="el" href="dump_8h_source.html#l00095">DumpHardwareHeader::crc64</a>, <a class="el" href="context_8h_source.html#l00212">aaruformat_context::dump_hardware_entries_with_data</a>, <a class="el" href="context_8h_source.html#l00232">aaruformat_context::dump_hardware_header</a>, <a class="el" href="enums_8h_source.html#l00156">DumpHardwareBlock</a>, <a class="el" href="dump_8h_source.html#l00093">DumpHardwareHeader::entries</a>, <a class="el" href="context_8h_source.html#l00316">DumpHardwareEntriesWithData::entry</a>, <a class="el" href="context_8h_source.html#l00317">DumpHardwareEntriesWithData::extents</a>, <a class="el" href="dump_8h_source.html#l00122">DumpHardwareEntry::extents</a>, <a class="el" href="log_8h_source.html#l00040">FATAL</a>, <a class="el" href="dump_8c_source.html#l00026">free_dump_hardware_entries()</a>, <a class="el" href="dump_8h_source.html#l00092">DumpHardwareHeader::identifier</a>, <a class="el" href="context_8h_source.html#l00292">aaruformat_context::is_writing</a>, <a class="el" href="dump_8h_source.html#l00094">DumpHardwareHeader::length</a>, <a class="el" href="context_8h_source.html#l00174">aaruformat_context::magic</a>, and <a class="el" href="log_8h_source.html#l00025">TRACE</a>.</p>
</div>
</div>