<!-- GENERATED by docs/sphinx/bin/02-reference from Storable.rs (xs_file_magic). Do not edit. -->

```{index} single: file_magic; Storable function
```
```{index} single: Storable::file_magic; Perl function
```

# file_magic

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

## Synopsis

```perl
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:

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

Quickly enumerate a directory of snapshots:

```perl
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`.

## See also

- `read_magic` — same inspection for an in-memory buffer.
- `retrieve` — read and thaw the file after validating its
  magic.
- `nstore` — produces files with `netorder => 1`.