Expand description
Printf-style format specifier substitution for magic rule messages.
Magic file messages frequently contain C-style format specifiers such as
%lld, %02x, or %s that reference the rule’s read value. GNU file
renders the message with the value substituted at the specifier’s
position; without this pass libmagic-rs would emit the literal
specifier tokens (e.g., at_offset %lld) and diverge visibly from
file(1) output.
The substitution is intentionally narrow: it supports the subset of
C’s printf syntax that appears in shipping magic corpora (notably
third_party/tests/searchbug.magic and the GNU file Magdir
collection). Unrecognized specifiers pass through literally with a
debug! log rather than erroring – matching the evaluator’s
graceful-skip discipline.
Width masking for hex specifiers uses crate::parser::ast::TypeKind::bit_width
so that e.g. a signed byte rendered with %02x produces the unsigned
8-bit interpretation (0xff, not 0xffffffffffffffff).
See the project plan at
docs/plans/2026-04-22-001-feat-meta-type-offset-and-format-substitution-plan.md
for scope, and GOTCHAS.md S14.2 for historical context.
Functions§
- format_
magic_ message - Substitute printf-style format specifiers in a magic rule message.