<trclass="memdesc:ad98012dc12a51d9eadbd79a25aab8299"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Sets the dump hardware block for the image during creation. <br/></td></tr>
<p>Retrieves the dump hardware block containing acquisition environment information. </p>
<p>Extracts the complete DumpHardwareBlock from the image, which documents the hardware and software environments used to create the image. A dump hardware block records one or more "dump environments" – typically combinations of physical devices (drives, controllers, adapters) and the software stacks that performed the read operations. This metadata is essential for understanding the imaging context, validating acquisition integrity, reproducing imaging conditions, and supporting forensic or archival documentation requirements.</p>
<p>Each environment entry includes hardware identification (manufacturer, model, revision, firmware, serial number), software identification (name, version, operating system), and optional extent ranges that specify which logical sectors or units were contributed by that particular environment. This structure supports complex imaging scenarios where multiple devices or software configurations were used to create a composite image.</p>
<p>The function reconstructs the complete on-disk binary representation of the dump hardware block, including the <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> followed by all entries with their variable-length UTF-8 strings and extent arrays. The reconstructed block includes a calculated CRC64 checksum over the payload data for integrity verification.</p>
<p>This function supports a two-call pattern for buffer size determination:</p><oltype="1">
<li>First call with insufficient buffer (or NULL) returns AARUF_ERROR_BUFFER_TOO_SMALL and sets *length to the required size (sizeof(DumpHardwareHeader) + total payload length)</li>
<li>Second call with properly sized buffer retrieves the complete block data</li>
</ol>
<p>Alternatively, if the caller already knows the buffer is large enough, a single call will succeed and populate the buffer with the complete dump hardware block.</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 image context). </td></tr>
<tr><tdclass="paramname">buffer</td><td>Pointer to a buffer that will receive the dump hardware block data. Must be large enough to hold the complete block (at least *length bytes on input). May be NULL to query the required buffer size. The buffer will contain the <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> followed by serialized entries, strings, and extent arrays on success. </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 the dump hardware block in bytes If the function returns AARUF_ERROR_BUFFER_TOO_SMALL, this will be updated to contain the required buffer size for a subsequent successful call.</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 dump hardware block. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The dump hardware block is present (identifier == DumpHardwareBlock)</li>
<li>The provided buffer is large enough (>= required length)</li>
<li>All hardware entries with their strings and extents are copied to the buffer</li>
<li>The <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> is written with calculated CRC64 at buffer offset 0</li>
<li>The *length parameter is set to the actual block size</li>
</ul>
</td></tr>
<tr><tdclass="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 <aclass="el"href="decls_8h.html#aefe69fae905b957bb4349ac59fad9bc7">aaruf_open()</a> or <aclass="el"href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013"title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<li><aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> (16 bytes): identifier, entries count, payload length, CRC64</li>
<li>For each entry (variable size):<ul>
<li><aclass="el"href="structDumpHardwareEntry.html"title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> (36 bytes): length fields for all strings and extent count</li>
<li>Array of <aclass="el"href="structDumpExtent.html"title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> structures (16 bytes each) if extent count > 0</li>
</ul>
</li>
<li>All strings are UTF-8 encoded and NOT null-terminated in the serialized block</li>
<li>String lengths are in bytes, not character counts</li>
</ul>
</dd>
<dd>
Dump Hardware Environments:<ul>
<li>Each entry represents one hardware/software combination used during imaging</li>
<li>Multiple entries support scenarios where different devices contributed different sectors</li>
<li>Extent arrays specify which logical sector ranges each environment contributed</li>
<li>Empty extent arrays (extents == 0) indicate the environment dumped the entire medium</li>
<li>Overlapping extents between entries may indicate verification passes or redundancy</li>
<li>model: Device model number (e.g., "PX-716A", "DRU-820A")</li>
<li>revision: Hardware revision identifier</li>
<li>firmware: Firmware version (e.g., "1.11", "KY08")</li>
<li>serial: Device serial number for unique identification</li>
</ul>
</dd>
<dd>
Software Identification Fields:<ul>
<li>softwareName: Dumping software name (e.g., "Aaru", "ddrescue", "IsoBuster")</li>
<li>softwareVersion: Software version (e.g., "5.3.0", "1.25")</li>
<li>softwareOperatingSystem: Host OS (e.g., "Linux 5.10.0", "Windows 10", "macOS 12.0")</li>
</ul>
</dd>
<dd>
CRC64 Calculation:<ul>
<li>The function calculates CRC64-ECMA over the payload (everything after the header)</li>
<li>The calculated CRC64 is stored in the returned <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a></li>
<li>This allows verification of the serialized block integrity</li>
<li>The CRC64 is computed from buffer data, not from the original context</li>
</ul>
</dd>
<dd>
Buffer Layout After Successful Call:<ul>
<li>Offset 0: <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> with calculated CRC64</li>
<li>Offset 16: First <aclass="el"href="structDumpHardwareEntry.html"title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a></li>
<li>Followed by: First entry's UTF-8 strings (in documented order)</li>
<li>Followed by: First entry's <aclass="el"href="structDumpExtent.html"title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> array (if extents > 0)</li>
<li>Repeated for all remaining entries</li>
</ul>
</dd>
<dd>
Use Cases:<ul>
<li>Forensic documentation requiring complete equipment chain of custody</li>
<li>Archival metadata for long-term preservation requirements</li>
<li>Reproducing imaging conditions for verification or re-imaging</li>
<li>Identifying firmware-specific issues or drive-specific behaviors</li>
<dlclass="section warning"><dt>Warning</dt><dd>This function reads from the in-memory dump hardware data loaded during <aclass="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>
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>
String data in the serialized block is NOT null-terminated. Applications parsing the buffer must use the length fields in <aclass="el"href="structDumpHardwareEntry.html"title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> to determine string boundaries. The library adds null terminators only for in-memory convenience.</dd>
<dd>
The function performs bounds checking during serialization. If calculated entry sizes exceed the buffer length, AARUF_ERROR_BUFFER_TOO_SMALL is returned even after the initial size check. This should not occur with properly sized buffers but protects against data corruption.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> for the block header structure definition. </dd>
<dd>
<aclass="el"href="structDumpHardwareEntry.html"title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> for the per-environment entry structure definition. </dd>
<dd>
<aclass="el"href="structDumpExtent.html"title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> for the extent range structure definition. </dd>
<dd>
<aclass="el"href="blocks_2dump_8c.html#a0e2cfc858c0551bc9bef11d5bdb85aac"title="Processes a dump hardware block from the image stream.">process_dumphw_block()</a> for the loading process during image opening. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="dump_8c_source.html#l00186">186</a> of file <aclass="el"href="dump_8c_source.html">dump.c</a>.</p>
<p>Sets the dump hardware block for the image during creation. </p>
<p>Embeds dump hardware information into the image being created. The dump hardware block documents the hardware and software environments used to create the image, recording one or more "dump
environments" – typically combinations of physical devices (drives, controllers, adapters) and the software stacks that performed the read operations. This metadata is essential for understanding the imaging context, validating acquisition integrity, reproducing imaging conditions, and supporting forensic or archival documentation requirements.</p>
<p>Each environment entry includes hardware identification (manufacturer, model, revision, firmware, serial number), software identification (name, version, operating system), and optional extent ranges that specify which logical sectors or units were contributed by that particular environment. This structure supports complex imaging scenarios where multiple devices or software configurations were used to create a composite image.</p>
<p>The function accepts a complete, pre-serialized DumpHardwareBlock in the on-disk binary format (as returned by <aclass="el"href="#a36af83897e131ba792c51ae8caec9984"title="Retrieves the dump hardware block containing acquisition environment information.">aaruf_get_dumphw()</a> or manually constructed). The block is validated for correct identifier, length consistency, and CRC64 integrity before being parsed and stored in the context. The function deserializes the binary block, extracts all entries with their variable-length UTF-8 strings and extent arrays, and creates null-terminated in-memory copies for internal use.</p>
<li>Block identifier validation (must be DumpHardwareBlock)</li>
<li>Length consistency (buffer length must equal sizeof(DumpHardwareHeader) + header.length)</li>
<li>CRC64 integrity verification (calculated CRC64 must match header.crc64)</li>
</ol>
<p><b>Parsing process:</b></p><oltype="1">
<li>Read and validate the <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> from the buffer</li>
<li>Allocate array for all dump hardware entries</li>
<li>For each entry:<ul>
<li>Read the <aclass="el"href="structDumpHardwareEntry.html"title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> structure (36 bytes)</li>
<li>Allocate and copy each non-empty UTF-8 string with +1 byte for null terminator</li>
<li>Allocate and copy the <aclass="el"href="structDumpExtent.html"title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> array if extents > 0</li>
</ul>
</li>
<li>Free any previously set dump hardware data</li>
<li>Store the new parsed data in ctx->dumpHardwareEntriesWithData</li>
<li>Store the header in ctx->dumpHardwareHeader</li>
</ol>
<p><b>Memory management:</b> If any memory allocation fails during parsing, all previously allocated memory for the new data is freed via the free_copy_and_error label, and AARUF_ERROR_NOT_ENOUGH_MEMORY is returned. Any existing dump hardware data in the context is freed before storing new data, ensuring no memory leaks when replacing dump hardware information.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">context</td><td>Pointer to the aaruformat context (must be a valid, write-enabled image context). </td></tr>
<tr><tdclass="paramname">data</td><td>Pointer to the dump hardware block data in on-disk binary format. Must contain a complete DumpHardwareBlock starting with <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> followed by all entries, strings, and extent arrays. Must not be NULL. </td></tr>
<tr><tdclass="paramname">length</td><td>Length of the dump hardware block data in bytes. Must equal sizeof(DumpHardwareHeader) + header.length for validation to succeed.</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 set dump hardware block. This is returned when:<ul>
<li>The context is valid and properly initialized</li>
<li>The context is opened in write mode (ctx->isWriting is true)</li>
<li>The data buffer contains a valid DumpHardwareBlock</li>
<li>The block identifier is DumpHardwareBlock</li>
<li>All entries with strings and extents are parsed and stored</li>
<li>Any previous dump hardware data is freed</li>
<li>ctx->dumpHardwareEntriesWithData is populated with parsed entries</li>
<li>ctx->dumpHardwareHeader is updated with the new header</li>
</ul>
</td></tr>
<tr><tdclass="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 <aclass="el"href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013"title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_READ_ONLY</td><td>(-13) The context is not opened for writing. This occurs when:<ul>
<li>The image was opened with <aclass="el"href="decls_8h.html#aefe69fae905b957bb4349ac59fad9bc7">aaruf_open()</a> instead of <aclass="el"href="decls_8h.html#a7065a9fefcaabfecc4184528f01ef013"title="Creates a new AaruFormat image file.">aaruf_create()</a></li>
<tr><tdclass="paramname">AARUF_ERROR_CANNOT_READ_BLOCK</td><td>(-6) Invalid block identifier. This occurs when:<ul>
<li>The identifier field in the <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> doesn't equal DumpHardwareBlock</li>
<li>The data buffer doesn't contain a valid dump hardware block</li>
<li>The block type is incorrect or corrupted</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_INCORRECT_DATA_SIZE</td><td>(-11) Invalid data or length. This occurs when:<ul>
<li>The data parameter is NULL</li>
<li>The length parameter is 0 (empty block)</li>
<li>The buffer length doesn't match sizeof(DumpHardwareHeader) + header.length</li>
<li>Length inconsistency indicates corrupted or incomplete block data</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_INVALID_BLOCK_CRC</td><td>(-10) CRC64 checksum mismatch. This occurs when:<ul>
<li>The calculated CRC64 over the payload doesn't match header.crc64</li>
<li>Block data is corrupted or tampered with</li>
<li>Block was not properly constructed or serialized</li>
</ul>
</td></tr>
<tr><tdclass="paramname">AARUF_ERROR_NOT_ENOUGH_MEMORY</td><td>(-8) Memory allocation failed. This occurs when:<ul>
<li>calloc() or malloc() failed to allocate memory for entries array</li>
<li>Failed to allocate memory for any string field (manufacturer, model, etc.)</li>
<li>Failed to allocate memory for extent arrays</li>
<li>System is out of memory or memory is severely fragmented</li>
<li>All partially allocated memory is freed before returning</li>
<li>The data buffer must contain a complete serialized DumpHardwareBlock</li>
<li>Format: <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> + repeated entries with strings and extents</li>
<li>All strings are UTF-8 encoded and NOT null-terminated in the buffer</li>
<li>The function adds null terminators when copying strings to internal storage</li>
<li>String lengths are in bytes, not character counts</li>
</ul>
</dd>
<dd>
Creating Block Data:<ul>
<li>Use <aclass="el"href="#a36af83897e131ba792c51ae8caec9984"title="Retrieves the dump hardware block containing acquisition environment information.">aaruf_get_dumphw()</a> to retrieve a block from an existing image</li>
<li>Manually construct by serializing <aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a>, entries, strings, and extents</li>
<li>Calculate CRC64-ECMA over the payload (everything after the header)</li>
<li>Ensure all length fields accurately reflect the data sizes</li>
<li>Ensure total buffer size equals sizeof(DumpHardwareHeader) + payload length</li>
<li>model: Device model number (e.g., "PX-716A", "DRU-820A")</li>
<li>revision: Hardware revision identifier</li>
<li>firmware: Firmware version (e.g., "1.11", "KY08")</li>
<li>serial: Device serial number for unique identification</li>
</ul>
</dd>
<dd>
Software Identification Fields:<ul>
<li>softwareName: Dumping software name (e.g., "Aaru", "ddrescue", "IsoBuster")</li>
<li>softwareVersion: Software version (e.g., "5.3.0", "1.25")</li>
<li>softwareOperatingSystem: Host OS (e.g., "Linux 5.10.0", "Windows 10", "macOS 12.0")</li>
</ul>
</dd>
<dd>
Extent Arrays:<ul>
<li>Each <aclass="el"href="structDumpExtent.html"title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> specifies a [start, end] logical sector range</li>
<li>Extents indicate which sectors this environment contributed</li>
<li>Empty extent arrays (extents == 0) mean the environment dumped entire medium</li>
<li>Extents are stored in the order provided in the input buffer</li>
</ul>
</dd>
<dd>
Memory Ownership:<ul>
<li>The function creates internal copies of all data</li>
<li>The caller retains ownership of the input data buffer</li>
<li>The caller may free the input buffer immediately after this function returns</li>
<li>Internal copies are freed during <aclass="el"href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49"title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a> or when replaced by another call</li>
</ul>
</dd>
<dd>
Replacing Existing Data:<ul>
<li>Calling this function multiple times replaces previous dump hardware data</li>
<li>All previous entries, strings, and extents are freed before storing new data</li>
<li>No memory leaks occur when updating dump hardware information</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The dump hardware block is only written to the image file during <aclass="el"href="decls_8h.html#a6823e139f81a9dfd08efcb0e9b213a49"title="Close an Aaru image context, flushing pending data structures and releasing resources.">aaruf_close()</a>. Changes made by this function are not immediately persisted to disk.</dd>
<dd>
CRC64 validation protects against corrupted blocks, but construction errors in the input buffer (incorrect lengths, misaligned data) may cause parsing to fail or produce incorrect results even with a valid checksum.</dd>
<dd>
The function assumes the input buffer is properly formatted and packed according to the DumpHardwareBlock specification. Malformed input may cause crashes or memory corruption.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="structDumpHardwareHeader.html"title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> for the block header structure definition. </dd>
<dd>
<aclass="el"href="structDumpHardwareEntry.html"title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> for the per-environment entry structure definition. </dd>
<dd>
<aclass="el"href="structDumpExtent.html"title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> for the extent range structure definition. </dd>
<dd>
<aclass="el"href="#a36af83897e131ba792c51ae8caec9984"title="Retrieves the dump hardware block containing acquisition environment information.">aaruf_get_dumphw()</a> for retrieving dump hardware from opened images. </dd>
<dd>
<aclass="el"href="close_8c.html#a796034966c1e918152e652635431dc39"title="Serialize the dump hardware block containing acquisition environment information.">write_dumphw_block()</a> for the serialization process during image closing. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="dump_8c_source.html#l00531">531</a> of file <aclass="el"href="dump_8c_source.html">dump.c</a>.</p>
<pclass="definition">Definition at line <aclass="el"href="dump_8c_source.html#l00026">26</a> of file <aclass="el"href="dump_8c_source.html">dump.c</a>.</p>
<pclass="reference">Referenced by <aclass="el"href="dump_8c_source.html#l00531">aaruf_set_dumphw()</a>.</p>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<divid="page-nav"class="page-nav-panel">
<divid="page-nav-resize-handle"></div>
<divid="page-nav-tree">
<divid="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<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>
