API Reference#

Complete API documentation for libmagic-rs library components.

Core Types#

MagicDatabase#

The main interface for loading magic rules and evaluating files.

use libmagic_rs::MagicDatabase;

Constructor Methods#

Evaluation Methods#

Accessor Methods#

Example#

use libmagic_rs::{MagicDatabase, EvaluationConfig};

// Using built-in rules
let db = MagicDatabase::with_builtin_rules()?;
let result = db.evaluate_file("sample.bin")?;
println!("Type: {}", result.description);

// With custom configuration using builder methods (required since v0.6.0)
let config = EvaluationConfig::default()
    .with_timeout_ms(Some(5000))
    .with_mime_types(true);
let db = MagicDatabase::with_builtin_rules_and_config(config)?;

// From file
let db = MagicDatabase::load_from_file("/usr/share/misc/magic")?;

EvaluationResult#

Result of magic rule evaluation.

use libmagic_rs::EvaluationResult;

Fields#

Example#

let result = db.evaluate_file("document.pdf")?;

println!("Description: {}", result.description);
println!("Confidence: {:.0}%", result.confidence * 100.0);

if let Some(mime) = &result.mime_type {
    println!("MIME Type: {}", mime);
}

println!("Evaluation time: {:.2}ms", result.metadata.evaluation_time_ms);

EvaluationConfig#

Configuration for rule evaluation behavior.

use libmagic_rs::EvaluationConfig;

Fields#

Preset Configurations#

// Default balanced settings
let config = EvaluationConfig::default();

// Optimized for speed
let config = EvaluationConfig::performance();
// - max_recursion_depth: 10
// - max_string_length: 1024
// - stop_at_first_match: true
// - timeout_ms: Some(1000)

// Optimized for completeness
let config = EvaluationConfig::comprehensive();
// - max_recursion_depth: 50
// - max_string_length: 32768
// - stop_at_first_match: false
// - enable_mime_types: true
// - timeout_ms: Some(30000)

Builder Methods#

Since v0.6.0, EvaluationConfig is #[non_exhaustive]. Use builder-style setters to construct configurations:

let config = EvaluationConfig::default()
    .with_max_recursion_depth(25)
    .with_max_string_length(16384)
    .with_stop_at_first_match(false)
    .with_mime_types(true)
    .with_timeout_ms(Some(5000));

Validation#

let config = EvaluationConfig {
    max_recursion_depth: 25,
    max_string_length: 16384,
    ..Default::default()
};

// Validate configuration
config.validate()?;

EvaluationMetadata#

Diagnostic information about the evaluation process.

use libmagic_rs::EvaluationMetadata;

Fields#

AST Types#

MagicRule#

Represents a parsed magic rule.

use libmagic_rs::MagicRule;

StrengthModifier#

Optional modifier for rule strength calculation.

use libmagic_rs::StrengthModifier;

OffsetSpec#

Offset specification for locating data.

use libmagic_rs::OffsetSpec;

Changes in v0.6.0#

OffsetSpec::Indirect added three fields:

• base_relative: bool - whether base_offset is relative to the previous match
• adjustment_op: Option<AdjustmentOp> - operation to apply between pointer value and adjustment
• result_relative: bool - whether the final computed offset is relative to the previous match

TypeKind#

Data type specifications.

use libmagic_rs::TypeKind;

MetaType#

Control-flow directives carried by TypeKind::Meta.

use libmagic_rs::parser::ast::MetaType;

Examples#

use libmagic_rs::{TypeKind, parser::ast::MetaType};

// A default fallback rule (fires when no sibling matched)
let default_type = TypeKind::Meta(MetaType::Default);

// Define a named subroutine
let name_type = TypeKind::Meta(MetaType::Name("riff_header".to_string()));

// Invoke that subroutine at a given offset
let use_type = TypeKind::Meta(MetaType::Use("riff_header".to_string()));

// Re-enter the root rule set at a resolved offset (ZIP-in-DOCX etc.)
let indirect_type = TypeKind::Meta(MetaType::Indirect);

// Emit the current file offset as a match value for printf substitution
let offset_type = TypeKind::Meta(MetaType::Offset);

Operator#

Comparison and bitwise operators for magic rule matching.

use libmagic_rs::Operator;

Examples#

use libmagic_rs::{MagicDatabase, Operator};

// Equal operator (default)
// Note: parse_magic_rule and parser::grammar module removed in v0.6.0
// This example is for conceptual reference only

// Bitwise AND - check if bit is set
// 0 byte &0x80

// Bitwise XOR - check for difference
// 0 byte ^0xFF

// Bitwise NOT - check complement
// 0 byte ~0xFF

// Any value - always matches
// 0 byte x

Value#

Value types for matching.

use libmagic_rs::Value;

The Value enum derives PartialEq but no longer derives Eq (removed in v0.5.0 to support floating-point values).

Endianness#

Byte order specification.

use libmagic_rs::Endianness;

Error Types#

LibmagicError#

Main error type for all library operations.

use libmagic_rs::LibmagicError;

Variants#

ParseError#

Errors during magic file parsing.

EvaluationError#

Errors during rule evaluation.

Example#

use libmagic_rs::{MagicDatabase, LibmagicError, ParseError};

match MagicDatabase::load_from_file("invalid.magic") {
    Ok(db) => println!("Loaded successfully"),
    Err(LibmagicError::ParseError(ParseError::InvalidSyntax { line, message })) => {
        eprintln!("Syntax error at line {}: {}", line, message);
    }
    Err(LibmagicError::IoError(e)) => {
        eprintln!("I/O error: {}", e);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Evaluator Module#

EvaluationContext#

Maintains evaluation state during rule processing.

use libmagic_rs::EvaluationContext;

Methods#

Removed in v0.6.0#

• increment_recursion_depth() - removed
• decrement_recursion_depth() - removed

MatchResult (Evaluator)#

Result from internal evaluation.

use libmagic_rs::evaluator::MatchResult;

Output Module#

MatchResult (Output)#

Structured match result for output formatting.

use libmagic_rs::output::MatchResult;

Fields#

Methods#

// Create basic result
let result = MatchResult::new(
    "PNG image".to_string(),
    0,
    Value::Bytes(vec![0x89, 0x50, 0x4e, 0x47])
);

// Create with full metadata
let result = MatchResult::with_metadata(
    "JPEG image".to_string(),
    0,
    2,
    Value::Bytes(vec![0xff, 0xd8]),
    vec!["image".to_string(), "jpeg".to_string()],
    85,
    Some("image/jpeg".to_string())
);

// Modify result
result.set_confidence(90);
result.add_rule_path("subtype".to_string());
result.set_mime_type(Some("image/jpeg".to_string()));

JSON Output#

use libmagic_rs::output::json::{format_json_output, format_json_line_output};

// Pretty-printed JSON (single file)
let json = format_json_output(&matches)?;

// JSON Lines (multiple files)
let json_line = format_json_line_output(path, &matches)?;

Type Aliases#

Re-exports#

The following types are re-exported from the root module for convenience:

// AST types
pub use parser::ast::{Endianness, MagicRule, OffsetSpec, Operator, StrengthModifier, TypeKind, Value};

// Evaluator types
pub use evaluator::{EvaluationContext, MatchResult};

// Error types
pub use error::{EvaluationError, LibmagicError, ParseError};

Thread Safety#

• MagicDatabase is Send + Sync (since v0.6.0) and can be shared across threads with appropriate synchronization
• EvaluationConfig is Send + Sync (plain data)
• For multi-threaded use, wrap MagicDatabase in Arc<MagicDatabase> to share a single instance, or create separate instances per thread

Version Compatibility#

• Minimum Rust Version: 1.85
• Edition: 2024
• License: Apache-2.0
• Current Version: 0.6.0

Breaking Changes in v0.6.0#

• EvaluationConfig is now #[non_exhaustive] - struct literal construction is no longer supported for external crates; use builder methods (with_max_recursion_depth, with_max_string_length, with_stop_at_first_match, with_mime_types, with_timeout_ms) or ..Default::default()
• MagicRule has a new value_transform field
• MagicDatabase now implements Send + Sync (see Thread Safety section)
• Multiple enums are now #[non_exhaustive]: OffsetSpec, LibmagicError, IoError, Operator, TypeReadError, ParseError, Value, TypeKind, EvaluationError - pattern matching must include wildcard arms
• OffsetSpec::Indirect has new fields: base_relative, adjustment_op, result_relative
• EvaluationContext methods increment_recursion_depth() and decrement_recursion_depth() removed
• parser::grammar module removed along with functions like parse_magic_rule, parse_offset, parse_number, parse_value, parse_operator, parse_type, parse_type_and_operator, parse_message, parse_comment, is_empty_line, is_comment_line, has_continuation, is_strength_directive, parse_strength_directive, parse_rule_offset
• parse_text_magic_file return type changed from Result<Vec<MagicRule>, ParseError> to Result<ParsedMagic, ParseError>; callers must destructure ParsedMagic { rules, name_table }. load_magic_file and load_magic_directory return the same new type
• evaluate_single_rule parameter count changed from 2 to 3

Breaking Changes in v0.5.0#

• TypeKind enum: Added Float { endian } and Double { endian } variants for IEEE 754 floating-point support
• TypeKind::String discriminant changed from 4 to 6 to accommodate new float types
• Value enum: Added Float(f64) variant for floating-point values
• Value enum: No longer derives Eq trait (only PartialEq is available due to floating-point values)
• RuleMatch struct: Added type_kind: TypeKind field to indicate the type used for matching

Breaking Changes (post-0.5.0, pre-0.6.0)#

• Parser functions (parse_text_magic_file, load_magic_file, load_magic_directory) now return ParsedMagic { rules, name_table } instead of Vec<MagicRule>. External consumers can only access the public rules field — name_table is pub(crate) and managed internally by MagicDatabase. Typical usage: let parsed = parse_text_magic_file(&source)?; /* use parsed.rules */. The library wires name_table through MagicDatabase::load_from_file automatically; direct access is not required (or supported) for external code.
• Rule messages are now rendered through printf-style format substitution: specifiers like %d, %x, %02x, %s, %lld are replaced with the rule's read value at output time. Literal % in rule messages must be escaped as %%. Messages that were previously emitted verbatim with bare % characters will now be interpreted as format specifiers — this is a visible behavior change for existing magic files that used % for non-formatting purposes.

Breaking Changes in v0.2.0#

• TypeKind::Byte changed from a unit variant to a struct variant Byte { signed } to support explicit signedness
• Added comparison operators: LessThan, GreaterThan, LessEqual, GreaterEqual to the Operator enum (breaking change due to exhaustive enum)

For complete API documentation with examples, run:

cargo doc --open