file_magic#

Inspect a file’s Storable header without thawing, returning metadata as a hash reference.

Synopsis#

use Storable qw(file_magic);
my $info = file_magic("data.bin");
die "not Storable" unless $info;

What you get back#

A hash reference describing the file’s header, or undef if the file does not exist, cannot be opened, or does not begin with a valid Storable tag. Keys:

file — the path that was inspected.
netorder — 1 if the payload is network-order (nstore / nstore_fd), 0 otherwise.
major, minor — format version numbers.
hdrsize — number of bytes of framing before the payload proper.

Examples#

Decide whether to trust an uploaded file:

my $info = file_magic($upload);
die "rejecting non-Storable upload" unless $info;
warn "portable payload" if $info->{netorder};

Quickly enumerate a directory of snapshots:

for my $f (glob "snapshots/*.bin") {
    my $m = file_magic($f) or next;
    printf "%s: v%d.%d\n", $f, $m->{major}, $m->{minor};
}

Edge cases#

Reads only the first 64 bytes; large files are not scanned in full, so this is cheap on any size.
Returns undef rather than croaking on a missing or unreadable file.

Differences from upstream#

Upstream populates additional keys such as byteorder, intsize, longsize, ptrsize, nvsize, and version_nv. pperl’s header does not record those fields, so they are omitted rather than filled with placeholder values. major / minor are fixed at 2 / 11 to match upstream’s version baseline that most callers look for. Pinned by t/81-xs-native/Storable/200-file-magic.t and t/81-xs-native/Storable/310-file-magic-accuracy.t.