nstore#

Serialise a referenced structure in network byte order and write it to a named file.

Synopsis#

use Storable qw(nstore retrieve);
nstore(\%data, "portable.bin") or die "write failed";
my $data = retrieve("portable.bin");    # works on any host

What you get back#

Returns 1 on success. The file holds the same portable byte string nfreeze would produce, prefixed with the network-order marker. retrieve auto-detects that marker, so the reader side does not need a different function.

Examples#

Write a configuration cache that any client can read:

nstore(\%config, "/srv/shared/config.bin");

Edge cases#

  • First argument must be a reference; croaks with Not a reference otherwise.

  • If the file cannot be opened for writing, croaks with Storable: can't open file for writing.

  • Slightly slower than store on little-endian hosts because every multi-byte value is byte-swapped on the way out.

Differences from upstream#

  • Byte layout is not wire-compatible with upstream Storable’s network-order format. Files round-trip only through pperl’s retrieve. Pinned by t/81-xs-native/Storable/250-nstore.t and t/81-xs-native/Storable/270-nfreeze-byteorder.t.

See also#

  • retrieve — matching reader; auto-detects byte order.

  • store — faster same-architecture variant.

  • nfreeze — produce bytes in memory without a file.

  • nstore_fd — write portable bytes to an open filehandle.