<trclass="memdesc:a74c444fbd394f58aefd2fabff221231b"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Identifies a file as an AaruFormat image using a file path. <br/></td></tr>
<trclass="memdesc:a6f30353aff3ece1e889542c26f7146e2"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Identifies a file as an AaruFormat image using an open stream. <br/></td></tr>
<p>Identifies a file as an AaruFormat image using a file path. </p>
<p>Opens the file at the given path and determines if it is an AaruFormat image by examining the file header for valid AaruFormat signatures and version information. This function provides a simple file-based interface that handles file opening, identification, and cleanup automatically. It delegates the actual identification logic to <aclass="el"href="#a6f30353aff3ece1e889542c26f7146e2"title="Identifies a file as an AaruFormat image using an open stream.">aaruf_identify_stream()</a>.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">filename</td><td>Path to the file to identify (must be accessible and readable).</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following values: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">100</td><td>Maximum confidence - Definitive AaruFormat image. This is returned when:<ul>
<li>The file header contains a valid AaruFormat signature (DIC_MAGIC or AARU_MAGIC)</li>
<li>The image major version is less than or equal to the supported version (AARUF_VERSION)</li>
<li>The file structure passes all header validation checks</li>
<li>This indicates the file is definitely a supported AaruFormat image</li>
</ul>
</td></tr>
<tr><tdclass="paramname">0</td><td>Not recognized - File is not an AaruFormat image. This is returned when:<ul>
<li>The file header doesn't contain a recognized AaruFormat signature</li>
<li>The image major version exceeds the maximum supported version</li>
<li>The file header cannot be read completely (file too small or corrupted)</li>
<li>The file format doesn't match AaruFormat specifications</li>
</ul>
</td></tr>
<tr><tdclass="paramname">Positive</td><td>errno values - File access errors from system calls. Common values include:<ul>
<li>ENOENT (2) - File not found or path doesn't exist</li>
<li>EACCES (13) - Permission denied, file not readable</li>
<li>EISDIR (21) - Path refers to a directory, not a file</li>
<li>EMFILE (24) - Too many open files (process limit reached)</li>
<li>ENFILE (23) - System limit on open files reached</li>
<li>ENOMEM (12) - Insufficient memory to open file</li>
<li>EIO (5) - I/O error occurred during file access</li>
<li>Other platform-specific errno values from fopen()</li>
<li>Opens the file in binary read mode ("rb")</li>
<li>Delegates identification to <aclass="el"href="#a6f30353aff3ece1e889542c26f7146e2"title="Identifies a file as an AaruFormat image using an open stream.">aaruf_identify_stream()</a> for actual header analysis</li>
<li>Automatically closes the file stream regardless of identification result</li>
<li>Returns system errno values directly if file opening fails</li>
</ul>
</dd>
<dd>
Confidence Scoring:<ul>
<li>Uses binary scoring: 100 (definitive match) or 0 (no match)</li>
<li>No intermediate confidence levels are returned</li>
<li>Designed for simple yes/no identification rather than probabilistic matching</li>
</ul>
</dd>
<dd>
Version Compatibility:<ul>
<li>Only recognizes AaruFormat versions up to AARUF_VERSION</li>
<li>Future versions beyond library support are treated as unrecognized</li>
<li>Backwards compatible with older DIC_MAGIC identifiers</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The function opens and closes the file for each identification. For repeated operations on the same file, consider using <aclass="el"href="#a6f30353aff3ece1e889542c26f7146e2"title="Identifies a file as an AaruFormat image using an open stream.">aaruf_identify_stream()</a> with a pre-opened stream for better performance.</dd>
<dd>
File access permissions and availability are checked at runtime. Network files or files on removable media may cause variable access times.</dd>
<dd>
The function performs minimal file content validation. A positive result indicates the file appears to be AaruFormat but doesn't guarantee the entire file is valid or uncorrupted. </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="identify_8c_source.html#l00084">84</a> of file <aclass="el"href="identify_8c_source.html">identify.c</a>.</p>
<pclass="reference">References <aclass="el"href="decls_8h_source.html#l00045">AARU_CALL</a>, <aclass="el"href="decls_8h_source.html#l00054">AARU_EXPORT</a>, and <aclass="el"href="identify_8c_source.html#l00163">aaruf_identify_stream()</a>.</p>
<p>Identifies a file as an AaruFormat image using an open stream. </p>
<p>Determines if the provided stream is an AaruFormat image by reading and validating the file header at the beginning of the stream. This function performs the core identification logic by checking for valid AaruFormat signatures and version compatibility. It's designed to work with any FILE stream, making it suitable for integration with existing file handling code.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">image_stream</td><td>Open FILE stream positioned at any location (will be repositioned to start).</td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>Returns one of the following values: </dd></dl>
<dlclass="retval"><dt>Return values</dt><dd>
<tableclass="retval">
<tr><tdclass="paramname">100</td><td>Maximum confidence - Definitive AaruFormat image. This is returned when:<ul>
<li>The stream is successfully repositioned to the beginning</li>
<li>The AaruFormat header is successfully read (<aclass="el"href="structAaruHeader.html"title="Version 1 container header placed at offset 0 for legacy / initial format.">AaruHeader</a> structure)</li>
<li>The header identifier matches either DIC_MAGIC or AARU_MAGIC (valid signatures)</li>
<li>The image major version is less than or equal to AARUF_VERSION (supported version)</li>
<li>All validation checks pass indicating a compatible AaruFormat image</li>
</ul>
</td></tr>
<tr><tdclass="paramname">0</td><td>Not recognized - Stream is not an AaruFormat image. This is returned when:<ul>
<li>The stream parameter is NULL</li>
<li>Cannot read a complete <aclass="el"href="structAaruHeader.html"title="Version 1 container header placed at offset 0 for legacy / initial format.">AaruHeader</a> structure from the stream (file too small)</li>
<li>The header identifier doesn't match DIC_MAGIC or AARU_MAGIC (wrong format)</li>
<li>The image major version exceeds AARUF_VERSION (unsupported future version)</li>
<li>Any validation check fails indicating the stream is not a valid AaruFormat image</li>
<li>Always seeks to position 0 at the beginning of the function</li>
<li>Reads exactly one <aclass="el"href="structAaruHeader.html"title="Version 1 container header placed at offset 0 for legacy / initial format.">AaruHeader</a> structure (size depends on format version)</li>
<li>Does not restore the original stream position after identification</li>
<li>Stream remains open and positioned after the header on function return</li>
</ul>
</dd>
<dd>
Signature Recognition:<ul>
<li>DIC_MAGIC: Legacy identifier from original DiscImageChef format</li>
<li>AARU_MAGIC: Current AaruFormat identifier</li>
<li>Both signatures are accepted for backwards compatibility</li>
<li>Signature validation is performed using exact byte matching</li>
</ul>
</dd>
<dd>
Version Validation:<ul>
<li>Only checks the major version number for compatibility</li>
<li>Minor version differences are ignored (assumed backwards compatible)</li>
<li>Future major versions are rejected to prevent compatibility issues</li>
<li>Version check prevents attempting to read unsupported format variants</li>
</ul>
</dd>
<dd>
Confidence Scoring:<ul>
<li>Binary result: 100 (definitive) or 0 (not recognized)</li>
<li>No probabilistic or partial matching</li>
<li>Designed for definitive identification rather than format detection</li>
</ul>
</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>The function modifies the stream position by seeking to the beginning and reading the header. The stream position is not restored.</dd>
<dd>
This function performs only header-level validation. A positive result indicates the file appears to have a valid AaruFormat header but doesn't guarantee the entire image structure is valid or uncorrupted.</dd>
<dd>
The stream must support seeking operations. Non-seekable streams (like pipes or network streams) may cause undefined behavior.</dd>
<dd>
No error codes are returned for I/O failures during header reading. Such failures result in a return value of 0 (not recognized). </dd></dl>
<pclass="definition">Definition at line <aclass="el"href="identify_8c_source.html#l00163">163</a> of file <aclass="el"href="identify_8c_source.html">identify.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>
