Printf-Style Format Substitution In Rule Messages#

Magic(5) rule messages frequently contain C-style format specifiers — at_offset %lld, followed_by 0x%02x, version %d.%d — that reference the rule's matched value. libmagic-rs resolves these at description-assembly time via format_magic_message in src/output/format.rs. Without this pass, the library would emit literal specifier tokens and diverge visibly from file(1) output. 1

format_magic_message is wired into MagicDatabase::build_result via concatenate_messages, which calls it once per RuleMatch before appending to the output string. 2

Supported Specifiers#

The supported conversion set covers the subset appearing in shipping magic corpora 3:

Width and padding modifiers are honored: %05d, %-5d, %#06x. 4 The + and flags are parsed for syntactic completeness but have no rendering effect. 5

Length modifiers (l, ll, h, hh, j, z, t) are consumed by the parser and silently ignored — all numeric rendering uses u64/i64 width regardless. 6

Width values are capped at MAX_FORMAT_WIDTH (4096) to prevent unbounded allocation from crafted magic rules. 7

Hex Masking via TypeKind::bit_width()#

%x, %X, and %o call coerce_to_u64_masked, which masks the coerced u64 to the natural bit width of the rule's TypeKind:

This prevents a signed byte carrying -1 (stored as i64::MAX-equivalent after sign-extension) from rendering as ffffffffffffffff when the user expects ff, matching GNU file output. 8 Regression tests test_byte_width_masking_on_negative_signed_byte and test_hex_width_masking_respects_16bit pin this behavior. 9

Composition with the \b Backspace Prefix#

concatenate_messages joins per-rule messages with a space separator, except when a rendered message starts with \u{0008} (backspace), in which case the backspace is stripped and no leading space is inserted. 10 11

Crucially, substitution runs before the backspace check. A rule with message \b, version %s correctly produces:

Ansible Vault text, version 1.1

rather than Ansible Vault text , version 1.1. 12

Unrecognized Specifier Pass-Through#

Any specifier not in the supported subset (e.g., %q) returns None from render, which causes format_magic_message to emit the literal specifier text and log a debug! message. 13 A malformed magic file cannot crash description rendering. 14

A trailing bare % with nothing following also passes through literally. 15

Non-ASCII UTF-8 Slice Fix#

The function scans the template at the byte level but copies plain-text runs as string slices (&template[plain_start..i]) rather than byte-by-byte. 16 This is safe because % is ASCII (0x25) and cannot appear as a UTF-8 continuation byte (always >= 0x80), so byte-level scanning never splits a multi-byte sequence.

The earlier byte-by-byte approach used out.push(b as char), which mapped bytes 0x80–0xFF to Latin-1 code points, corrupting a two-byte sequence like é (0xC3 0xA9) into two separate characters. The fix is exercised by the test_non_ascii_template_preserved test (covering café, → ok ←, über).

Testing#

All tests live in the #[cfg(test)] block of src/output/format.rs. 17 Key cases:

• test_hex_substitution_with_byte_width_masking — canonical searchbug.magic case (0x%02x against ubyte), alt-form prefix placement, zero-value alt-form suppression. 18
• test_byte_width_masking_on_negative_signed_byte / test_hex_width_masking_respects_16bit — regression guards for sign-extension masking. 9
• test_unknown_specifier_pass_through — %q literal pass-through. 19
• test_width_cap_prevents_large_allocation — MAX_FORMAT_WIDTH safety. 20

Tests that simulate build_result manually (bypassing load_from_file) must either run messages through format_magic_message or use %-free message strings; unescaped % in RuleMatch::message is interpreted as a specifier. 21

References#

• Implementation: src/output/format.rs — format_magic_message, parse_spec, render, coerce_to_u64_masked
• Call site: src/lib.rs::concatenate_messages
• Canonical reference: GOTCHAS.md S14.2
• Backspace convention: GOTCHAS.md S14.1
• Feature status: AGENTS.md "Currently Implemented"
• TypeKind::bit_width(): src/parser/ast.rs