API Reference

Complete API documentation for libmagic-rs library components.

Core Types

MagicDatabase

The main interface for loading magic rules and evaluating files.

#![allow(unused)]
fn main() {
use libmagic_rs::MagicDatabase;
}

Constructor Methods

Evaluation Methods

Accessor Methods

Example

#![allow(unused)]
fn main() {
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
let config = EvaluationConfig {
    timeout_ms: Some(5000),
    enable_mime_types: true,
    ..Default::default()
};
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.

#![allow(unused)]
fn main() {
use libmagic_rs::EvaluationResult;
}

Fields

Example

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
use libmagic_rs::EvaluationConfig;
}

Fields

Preset Configurations

#![allow(unused)]
fn main() {
// 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)
}

Validation

#![allow(unused)]
fn main() {
let config = EvaluationConfig {
    max_recursion_depth: 25,
    max_string_length: 16384,
    ..Default::default()
};

// Validate configuration
config.validate()?;
}

EvaluationMetadata

Diagnostic information about the evaluation process.

#![allow(unused)]
fn main() {
use libmagic_rs::EvaluationMetadata;
}

Fields

AST Types

MagicRule

Represents a parsed magic rule.

#![allow(unused)]
fn main() {
use libmagic_rs::MagicRule;
}

StrengthModifier

Optional modifier for rule strength calculation.

#![allow(unused)]
fn main() {
use libmagic_rs::StrengthModifier;
}

OffsetSpec

Offset specification for locating data.

#![allow(unused)]
fn main() {
use libmagic_rs::OffsetSpec;
}

TypeKind

Data type specifications.

#![allow(unused)]
fn main() {
use libmagic_rs::TypeKind;
}

Operator

Comparison and bitwise operators for magic rule matching.

#![allow(unused)]
fn main() {
use libmagic_rs::Operator;
}

Examples

#![allow(unused)]
fn main() {
use libmagic_rs::{MagicDatabase, Operator};
use libmagic_rs::parser::grammar::parse_magic_rule;

// Equal operator (default)
let (_, rule) = parse_magic_rule("0 byte =0x7f").unwrap();
assert_eq!(rule.op, Operator::Equal);

// Bitwise AND - check if bit is set
let (_, rule) = parse_magic_rule("0 byte &0x80").unwrap();
assert_eq!(rule.op, Operator::BitwiseAnd);

// Bitwise XOR - check for difference
let (_, rule) = parse_magic_rule("0 byte ^0xFF").unwrap();
assert_eq!(rule.op, Operator::BitwiseXor);

// Bitwise NOT - check complement
let (_, rule) = parse_magic_rule("0 byte ~0xFF").unwrap();
assert_eq!(rule.op, Operator::BitwiseNot);

// Any value - always matches
let (_, rule) = parse_magic_rule("0 byte x").unwrap();
assert_eq!(rule.op, Operator::AnyValue);
}

Value

Value types for matching.

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
use libmagic_rs::Endianness;
}

Error Types

LibmagicError

Main error type for all library operations.

#![allow(unused)]
fn main() {
use libmagic_rs::LibmagicError;
}

Variants

ParseError

Errors during magic file parsing.

EvaluationError

Errors during rule evaluation.

Example

#![allow(unused)]
fn main() {
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.

#![allow(unused)]
fn main() {
use libmagic_rs::EvaluationContext;
}

Methods

MatchResult (Evaluator)

Result from internal evaluation.

#![allow(unused)]
fn main() {
use libmagic_rs::evaluator::MatchResult;
}

Output Module

MatchResult (Output)

Structured match result for output formatting.

#![allow(unused)]
fn main() {
use libmagic_rs::output::MatchResult;
}

Fields

Methods

#![allow(unused)]
fn main() {
// 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

#![allow(unused)]
fn main() {
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:

#![allow(unused)]
fn main() {
// 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 not Send or Sync by default due to internal state
• EvaluationConfig is Send + Sync (plain data)
• For multi-threaded use, create separate MagicDatabase instances per thread or use appropriate synchronization

Version Compatibility

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

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 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