identify.c File Reference

#include <errno.h>
#include <stdio.h>
#include <aaruformat.h>
#include "internal.h"

Go to the source code of this file.

Functions
int	aaruf_identify (const char *filename)
	Identifies a file as an AaruFormat image using a file path.
int	aaruf_identify_stream (FILE *image_stream)
	Identifies a file as an AaruFormat image using an open stream.

Function Documentation

aaruf_identify()

int aaruf_identify

(

const char *

filename

)

Identifies a file as an AaruFormat image using a file path.

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 aaruf_identify_stream().

Parameters

filename

Path to the file to identify (must be accessible and readable).

Returns

Returns one of the following values:

Return values

100	Maximum confidence - Definitive AaruFormat image. This is returned when: The file header contains a valid AaruFormat signature (DIC_MAGIC or AARU_MAGIC) The image major version is less than or equal to the supported version (AARUF_VERSION) The file structure passes all header validation checks This indicates the file is definitely a supported AaruFormat image
0	Not recognized - File is not an AaruFormat image. This is returned when: The file header doesn't contain a recognized AaruFormat signature The image major version exceeds the maximum supported version The file header cannot be read completely (file too small or corrupted) The file format doesn't match AaruFormat specifications
Positive	errno values - File access errors from system calls. Common values include: ENOENT (2) - File not found or path doesn't exist EACCES (13) - Permission denied, file not readable EISDIR (21) - Path refers to a directory, not a file EMFILE (24) - Too many open files (process limit reached) ENFILE (23) - System limit on open files reached ENOMEM (12) - Insufficient memory to open file EIO (5) - I/O error occurred during file access Other platform-specific errno values from fopen()

Note

Identification Process:

• Opens the file in binary read mode ("rb")
• Delegates identification to aaruf_identify_stream() for actual header analysis
• Automatically closes the file stream regardless of identification result
• Returns system errno values directly if file opening fails

Confidence Scoring:

• Uses binary scoring: 100 (definitive match) or 0 (no match)
• No intermediate confidence levels are returned
• Designed for simple yes/no identification rather than probabilistic matching

Version Compatibility:

• Only recognizes AaruFormat versions up to AARUF_VERSION
• Future versions beyond library support are treated as unrecognized
• Backwards compatible with older DIC_MAGIC identifiers

Warning

The function opens and closes the file for each identification. For repeated operations on the same file, consider using aaruf_identify_stream() with a pre-opened stream for better performance.

File access permissions and availability are checked at runtime. Network files or files on removable media may cause variable access times.

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.

Definition at line 86 of file identify.c.

References AARU_CALL, AARU_EXPORT, aaruf_identify(), and aaruf_identify_stream().

Referenced by aaruf_identify().

aaruf_identify_stream()

int aaruf_identify_stream

(

FILE *

image_stream

)

Identifies a file as an AaruFormat image using an open stream.

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.

Parameters

image_stream

Open FILE stream positioned at any location (will be repositioned to start).

Returns

Returns one of the following values:

Return values

100

Maximum confidence - Definitive AaruFormat image. This is returned when: The stream is successfully repositioned to the beginning The AaruFormat header is successfully read (AaruHeader structure) The header identifier matches either DIC_MAGIC or AARU_MAGIC (valid signatures) The image major version is less than or equal to AARUF_VERSION (supported version) All validation checks pass indicating a compatible AaruFormat image

0

Not recognized - Stream is not an AaruFormat image. This is returned when: The stream parameter is NULL Cannot read a complete AaruHeader structure from the stream (file too small) The header identifier doesn't match DIC_MAGIC or AARU_MAGIC (wrong format) The image major version exceeds AARUF_VERSION (unsupported future version) Any validation check fails indicating the stream is not a valid AaruFormat image

Note

Stream Handling:

• Always seeks to position 0 at the beginning of the function
• Reads exactly one AaruHeader structure (size depends on format version)
• Does not restore the original stream position after identification
• Stream remains open and positioned after the header on function return

Signature Recognition:

• DIC_MAGIC: Legacy identifier from original DiscImageChef format
• AARU_MAGIC: Current AaruFormat identifier
• Both signatures are accepted for backwards compatibility
• Signature validation is performed using exact byte matching

Version Validation:

• Only checks the major version number for compatibility
• Minor version differences are ignored (assumed backwards compatible)
• Future major versions are rejected to prevent compatibility issues
• Version check prevents attempting to read unsupported format variants

Confidence Scoring:

• Binary result: 100 (definitive) or 0 (not recognized)
• No probabilistic or partial matching
• Designed for definitive identification rather than format detection

Warning

The function modifies the stream position by seeking to the beginning and reading the header. The stream position is not restored.

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.

The stream must support seeking operations. Non-seekable streams (like pipes or network streams) may cause undefined behavior.

No error codes are returned for I/O failures during header reading. Such failures result in a return value of 0 (not recognized).

Definition at line 165 of file identify.c.

References AARU_CALL, AARU_EXPORT, AARU_MAGIC, aaruf_fseek(), aaruf_identify_stream(), AARUF_VERSION, DIC_MAGIC, AaruHeader::identifier, and AaruHeader::imageMajorVersion.

Referenced by aaruf_identify(), and aaruf_identify_stream().