2 # Copyright (c) 1995-2000, Raphael Manfredi
4 # You may redistribute only under the same terms as Perl 5, as specified
5 # in the README file that comes with the distribution.
10 package Storable; @ISA = qw(Exporter DynaLoader);
12 @EXPORT = qw(store retrieve);
14 nstore store_fd nstore_fd fd_retrieve
18 lock_store lock_nstore lock_retrieve
23 use vars qw($canonical $forgive_me $VERSION);
26 *AUTOLOAD = \&AutoLoader::AUTOLOAD; # Grrr...
29 # Use of Log::Agent is optional
34 eval "use Log::Agent";
40 # They might miss :flock in Fcntl
44 if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) {
45 Fcntl->import(':flock');
55 # clone context under threads
56 Storable::init_perinterp();
59 # Can't Autoload cleanly as this clashes 8.3 with &retrieve
60 sub retrieve_fd { &fd_retrieve } # Backward compatibility
62 # By default restricted hashes are downgraded on earlier perls.
64 $Storable::downgrade_restricted = 1;
65 $Storable::accept_future_minor = 1;
70 # Use of Log::Agent is optional. If it hasn't imported these subs then
71 # Autoloader will kindly supply our fallback implementation.
83 # Determine whether locking is possible, but only when needed.
86 sub CAN_FLOCK; my $CAN_FLOCK; sub CAN_FLOCK {
87 return $CAN_FLOCK if defined $CAN_FLOCK;
88 require Config; import Config;
91 $Config{'d_fcntl_can_lock'} ||
98 # To recognize the data files of the Perl module Storable,
99 # the following lines need to be added to the local magic(5) file,
100 # usually either /usr/share/misc/magic or /etc/magic.
102 0 string perl-store perl Storable(v0.6) data
103 >4 byte >0 (net-order %d)
104 >>4 byte &01 (network-ordered)
105 >>4 byte =3 (major 1)
106 >>4 byte =2 (major 1)
108 0 string pst0 perl Storable(v0.7) data
110 >>4 byte &01 (network-ordered)
111 >>4 byte =5 (major 2)
112 >>4 byte =4 (major 2)
113 >>5 byte >0 (minor %d)
119 open(my $fh, "<", $file) || die "Can't open '$file': $!";
121 defined(sysread($fh, my $buf, 32)) || die "Can't read from '$file': $!";
124 $file = "./$file" unless $file; # ensure TRUE value
126 return read_magic($buf, $file);
130 my($buf, $file) = @_;
133 my $buflen = length($buf);
135 if ($buf =~ s/^(pst0|perl-store)//) {
137 $info{file} = $file || 1;
140 return undef if $file;
144 return undef unless length($buf);
147 if ($magic eq "perl-store" && ord(substr($buf, 0, 1)) > 1) {
152 $net_order = ord(substr($buf, 0, 1, ""));
153 my $major = $net_order >> 1;
154 return undef if $major > 4; # sanity (assuming we never go that high)
155 $info{major} = $major;
158 return undef unless length($buf);
159 my $minor = ord(substr($buf, 0, 1, ""));
160 $info{minor} = $minor;
161 $info{version} = "$major.$minor";
162 $info{version_nv} = sprintf "%d.%03d", $major, $minor;
165 $info{version} = $major;
168 $info{version_nv} ||= $info{version};
169 $info{netorder} = $net_order;
171 unless ($net_order) {
172 return undef unless length($buf);
173 my $len = ord(substr($buf, 0, 1, ""));
174 return undef unless length($buf) >= $len;
175 return undef unless $len == 4 || $len == 8; # sanity
176 $info{byteorder} = substr($buf, 0, $len, "");
177 $info{intsize} = ord(substr($buf, 0, 1, ""));
178 $info{longsize} = ord(substr($buf, 0, 1, ""));
179 $info{ptrsize} = ord(substr($buf, 0, 1, ""));
180 if ($info{version_nv} >= 2.002) {
181 return undef unless length($buf);
182 $info{nvsize} = ord(substr($buf, 0, 1, ""));
185 $info{hdrsize} = $buflen - length($buf);
191 sprintf "%d.%03d", BIN_MAJOR(), BIN_MINOR();
194 sub BIN_WRITE_VERSION_NV {
195 sprintf "%d.%03d", BIN_MAJOR(), BIN_WRITE_MINOR();
201 # Store target object hierarchy, identified by a reference to its root.
202 # The stored object tree may later be retrieved to memory via retrieve.
203 # Returns undef if an I/O error occurred, in which case the file is
207 return _store(\&pstore, @_, 0);
213 # Same as store, but in network order.
216 return _store(\&net_pstore, @_, 0);
222 # Same as store, but flock the file first (advisory locking).
225 return _store(\&pstore, @_, 1);
231 # Same as nstore, but flock the file first (advisory locking).
234 return _store(\&net_pstore, @_, 1);
237 # Internal store to file routine
241 my ($file, $use_locking) = @_;
242 logcroak "not a reference" unless ref($self);
243 logcroak "wrong argument number" unless @_ == 2; # No @foo in arglist
246 open(FILE, ">>$file") || logcroak "can't write into $file: $!";
247 unless (&CAN_FLOCK) {
248 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
251 flock(FILE, LOCK_EX) ||
252 logcroak "can't get exclusive lock on $file: $!";
254 # Unlocking will happen when FILE is closed
256 open(FILE, ">$file") || logcroak "can't create $file: $!";
258 binmode FILE; # Archaic systems...
259 my $da = $@; # Don't mess if called from exception handler
261 # Call C routine nstore or pstore, depending on network order
262 eval { $ret = &$xsptr(*FILE, $self) };
263 close(FILE) or $ret = undef;
264 unlink($file) or warn "Can't unlink $file: $!\n" if $@ || !defined $ret;
265 logcroak $@ if $@ =~ s/\.?\n$/,/;
267 return $ret ? $ret : undef;
273 # Same as store, but perform on an already opened file descriptor instead.
274 # Returns undef if an I/O error occurred.
277 return _store_fd(\&pstore, @_);
283 # Same as store_fd, but in network order.
286 my ($self, $file) = @_;
287 return _store_fd(\&net_pstore, @_);
290 # Internal store routine on opened file descriptor
295 logcroak "not a reference" unless ref($self);
296 logcroak "too many arguments" unless @_ == 1; # No @foo in arglist
297 my $fd = fileno($file);
298 logcroak "not a valid file descriptor" unless defined $fd;
299 my $da = $@; # Don't mess if called from exception handler
301 # Call C routine nstore or pstore, depending on network order
302 eval { $ret = &$xsptr($file, $self) };
303 logcroak $@ if $@ =~ s/\.?\n$/,/;
304 local $\; print $file ''; # Autoflush the file if wanted
306 return $ret ? $ret : undef;
312 # Store oject and its hierarchy in memory and return a scalar
313 # containing the result.
316 _freeze(\&mstore, @_);
322 # Same as freeze but in network order.
325 _freeze(\&net_mstore, @_);
328 # Internal freeze routine
332 logcroak "not a reference" unless ref($self);
333 logcroak "too many arguments" unless @_ == 0; # No @foo in arglist
334 my $da = $@; # Don't mess if called from exception handler
336 # Call C routine mstore or net_mstore, depending on network order
337 eval { $ret = &$xsptr($self) };
338 logcroak $@ if $@ =~ s/\.?\n$/,/;
340 return $ret ? $ret : undef;
346 # Retrieve object hierarchy from disk, returning a reference to the root
347 # object of that tree.
356 # Same as retrieve, but with advisory locking.
362 # Internal retrieve routine
364 my ($file, $use_locking) = @_;
366 open(FILE, $file) || logcroak "can't open $file: $!";
367 binmode FILE; # Archaic systems...
369 my $da = $@; # Could be from exception handler
371 unless (&CAN_FLOCK) {
372 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
375 flock(FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!";
376 # Unlocking will happen when FILE is closed
378 eval { $self = pretrieve(*FILE) }; # Call C routine
380 logcroak $@ if $@ =~ s/\.?\n$/,/;
388 # Same as retrieve, but perform from an already opened file descriptor instead.
392 my $fd = fileno($file);
393 logcroak "not a valid file descriptor" unless defined $fd;
395 my $da = $@; # Could be from exception handler
396 eval { $self = pretrieve($file) }; # Call C routine
397 logcroak $@ if $@ =~ s/\.?\n$/,/;
405 # Recreate objects in memory from an existing frozen image created
406 # by freeze. If the frozen image passed is undef, return undef.
410 return undef unless defined $frozen;
412 my $da = $@; # Could be from exception handler
413 eval { $self = mretrieve($frozen) }; # Call C routine
414 logcroak $@ if $@ =~ s/\.?\n$/,/;
424 Storable - persistence for Perl data structures
429 store \%table, 'file';
430 $hashref = retrieve('file');
432 use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);
435 nstore \%table, 'file';
436 $hashref = retrieve('file'); # There is NO nretrieve()
438 # Storing to and retrieving from an already opened file
439 store_fd \@array, \*STDOUT;
440 nstore_fd \%table, \*STDOUT;
441 $aryref = fd_retrieve(\*SOCKET);
442 $hashref = fd_retrieve(\*SOCKET);
444 # Serializing to memory
445 $serialized = freeze \%table;
446 %table_clone = %{ thaw($serialized) };
448 # Deep (recursive) cloning
449 $cloneref = dclone($ref);
452 use Storable qw(lock_store lock_nstore lock_retrieve)
453 lock_store \%table, 'file';
454 lock_nstore \%table, 'file';
455 $hashref = lock_retrieve('file');
459 The Storable package brings persistence to your Perl data structures
460 containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be
461 conveniently stored to disk and retrieved at a later time.
463 It can be used in the regular procedural way by calling C<store> with
464 a reference to the object to be stored, along with the file name where
465 the image should be written.
467 The routine returns C<undef> for I/O problems or other internal error,
468 a true value otherwise. Serious errors are propagated as a C<die> exception.
470 To retrieve data stored to disk, use C<retrieve> with a file name.
471 The objects stored into that file are recreated into memory for you,
472 and a I<reference> to the root object is returned. In case an I/O error
473 occurs while reading, C<undef> is returned instead. Other serious
474 errors are propagated via C<die>.
476 Since storage is performed recursively, you might want to stuff references
477 to objects that share a lot of common data into a single array or hash
478 table, and then store that object. That way, when you retrieve back the
479 whole thing, the objects will continue to share what they originally shared.
481 At the cost of a slight header overhead, you may store to an already
482 opened file descriptor using the C<store_fd> routine, and retrieve
483 from a file via C<fd_retrieve>. Those names aren't imported by default,
484 so you will have to do that explicitly if you need those routines.
485 The file descriptor you supply must be already opened, for read
486 if you're going to retrieve and for write if you wish to store.
488 store_fd(\%table, *STDOUT) || die "can't store to stdout\n";
489 $hashref = fd_retrieve(*STDIN);
491 You can also store data in network order to allow easy sharing across
492 multiple platforms, or when storing on a socket known to be remotely
493 connected. The routines to call have an initial C<n> prefix for I<network>,
494 as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be
495 correctly restored so you don't have to know whether you're restoring
496 from native or network ordered data. Double values are stored stringified
497 to ensure portability as well, at the slight risk of loosing some precision
498 in the last decimals.
500 When using C<fd_retrieve>, objects are retrieved in sequence, one
501 object (i.e. one recursive tree) per associated C<store_fd>.
503 If you're more from the object-oriented camp, you can inherit from
504 Storable and directly store your objects by invoking C<store> as
505 a method. The fact that the root of the to-be-stored tree is a
506 blessed reference (i.e. an object) is special-cased so that the
507 retrieve does not provide a reference to that object but rather the
508 blessed object reference itself. (Otherwise, you'd get a reference
509 to that blessed object).
513 The Storable engine can also store data into a Perl scalar instead, to
514 later retrieve them. This is mainly used to freeze a complex structure in
515 some safe compact memory place (where it can possibly be sent to another
516 process via some IPC, since freezing the structure also serializes it in
517 effect). Later on, and maybe somewhere else, you can thaw the Perl scalar
518 out and recreate the original complex structure in memory.
520 Surprisingly, the routines to be called are named C<freeze> and C<thaw>.
521 If you wish to send out the frozen scalar to another machine, use
522 C<nfreeze> instead to get a portable image.
524 Note that freezing an object structure and immediately thawing it
525 actually achieves a deep cloning of that structure:
527 dclone(.) = thaw(freeze(.))
529 Storable provides you with a C<dclone> interface which does not create
530 that intermediary scalar but instead freezes the structure in some
531 internal memory space and then immediately thaws it out.
533 =head1 ADVISORY LOCKING
535 The C<lock_store> and C<lock_nstore> routine are equivalent to
536 C<store> and C<nstore>, except that they get an exclusive lock on
537 the file before writing. Likewise, C<lock_retrieve> does the same
538 as C<retrieve>, but also gets a shared lock on the file before reading.
540 As with any advisory locking scheme, the protection only works if you
541 systematically use C<lock_store> and C<lock_retrieve>. If one side of
542 your application uses C<store> whilst the other uses C<lock_retrieve>,
543 you will get no protection at all.
545 The internal advisory locking is implemented using Perl's flock()
546 routine. If your system does not support any form of flock(), or if
547 you share your files across NFS, you might wish to use other forms
548 of locking by using modules such as LockFile::Simple which lock a
549 file using a filesystem entry, instead of locking the file descriptor.
553 The heart of Storable is written in C for decent speed. Extra low-level
554 optimizations have been made when manipulating perl internals, to
555 sacrifice encapsulation for the benefit of greater speed.
557 =head1 CANONICAL REPRESENTATION
559 Normally, Storable stores elements of hashes in the order they are
560 stored internally by Perl, i.e. pseudo-randomly. If you set
561 C<$Storable::canonical> to some C<TRUE> value, Storable will store
562 hashes with the elements sorted by their key. This allows you to
563 compare data structures by comparing their frozen representations (or
564 even the compressed frozen representations), which can be useful for
565 creating lookup tables for complicated queries.
567 Canonical order does not imply network order; those are two orthogonal
570 =head1 CODE REFERENCES
572 Since Storable version 2.05, CODE references may be serialized with
573 the help of L<B::Deparse>. To enable this feature, set
574 C<$Storable::Deparse> to a true value. To enable deserialization,
575 C<$Storable::Eval> should be set to a true value. Be aware that
576 deserialization is done through C<eval>, which is dangerous if the
577 Storable file contains malicious data. You can set C<$Storable::Eval>
578 to a subroutine reference which would be used instead of C<eval>. See
579 below for an example using a L<Safe> compartment for deserialization
582 If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false
583 values, then the value of C<$Storable::forgive_me> (see below) is
584 respected while serializing and deserializing.
586 =head1 FORWARD COMPATIBILITY
588 This release of Storable can be used on a newer version of Perl to
589 serialize data which is not supported by earlier Perls. By default,
590 Storable will attempt to do the right thing, by C<croak()>ing if it
591 encounters data that it cannot deserialize. However, the defaults
592 can be changed as follows:
598 Perl 5.6 added support for Unicode characters with code points > 255,
599 and Perl 5.8 has full support for Unicode characters in hash keys.
600 Perl internally encodes strings with these characters using utf8, and
601 Storable serializes them as utf8. By default, if an older version of
602 Perl encounters a utf8 value it cannot represent, it will C<croak()>.
603 To change this behaviour so that Storable deserializes utf8 encoded
604 values as the string of bytes (effectively dropping the I<is_utf8> flag)
605 set C<$Storable::drop_utf8> to some C<TRUE> value. This is a form of
606 data loss, because with C<$drop_utf8> true, it becomes impossible to tell
607 whether the original data was the Unicode string, or a series of bytes
608 that happen to be valid utf8.
610 =item restricted hashes
612 Perl 5.8 adds support for restricted hashes, which have keys
613 restricted to a given set, and can have values locked to be read only.
614 By default, when Storable encounters a restricted hash on a perl
615 that doesn't support them, it will deserialize it as a normal hash,
616 silently discarding any placeholder keys and leaving the keys and
617 all values unlocked. To make Storable C<croak()> instead, set
618 C<$Storable::downgrade_restricted> to a C<FALSE> value. To restore
619 the default set it back to some C<TRUE> value.
621 =item files from future versions of Storable
623 Earlier versions of Storable would immediately croak if they encountered
624 a file with a higher internal version number than the reading Storable
625 knew about. Internal version numbers are increased each time new data
626 types (such as restricted hashes) are added to the vocabulary of the file
627 format. This meant that a newer Storable module had no way of writing a
628 file readable by an older Storable, even if the writer didn't store newer
631 This version of Storable will defer croaking until it encounters a data
632 type in the file that it does not recognize. This means that it will
633 continue to read files generated by newer Storable modules which are careful
634 in what they write out, making it easier to upgrade Storable modules in a
637 The old behaviour of immediate croaking can be re-instated by setting
638 C<$Storable::accept_future_minor> to some C<FALSE> value.
642 All these variables have no effect on a newer Perl which supports the
645 =head1 ERROR REPORTING
647 Storable uses the "exception" paradigm, in that it does not try to workaround
648 failures: if something bad happens, an exception is generated from the
649 caller's perspective (see L<Carp> and C<croak()>). Use eval {} to trap
652 When Storable croaks, it tries to report the error via the C<logcroak()>
653 routine from the C<Log::Agent> package, if it is available.
655 Normal errors are reported by having store() or retrieve() return C<undef>.
656 Such errors are usually I/O errors (or truncated stream errors at retrieval).
662 Any class may define hooks that will be called during the serialization
663 and deserialization process on objects that are instances of that class.
664 Those hooks can redefine the way serialization is performed (and therefore,
665 how the symmetrical deserialization should be conducted).
667 Since we said earlier:
669 dclone(.) = thaw(freeze(.))
671 everything we say about hooks should also hold for deep cloning. However,
672 hooks get to know whether the operation is a mere serialization, or a cloning.
674 Therefore, when serializing hooks are involved,
676 dclone(.) <> thaw(freeze(.))
678 Well, you could keep them in sync, but there's no guarantee it will always
679 hold on classes somebody else wrote. Besides, there is little to gain in
680 doing so: a serializing hook could keep only one attribute of an object,
681 which is probably not what should happen during a deep cloning of that
684 Here is the hooking interface:
688 =item C<STORABLE_freeze> I<obj>, I<cloning>
690 The serializing hook, called on the object during serialization. It can be
691 inherited, or defined in the class itself, like any other method.
693 Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating
694 whether we're in a dclone() or a regular serialization via store() or freeze().
696 Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized
697 is the serialized form to be used, and the optional $ref1, $ref2, etc... are
698 extra references that you wish to let the Storable engine serialize.
700 At deserialization time, you will be given back the same LIST, but all the
701 extra references will be pointing into the deserialized structure.
703 The B<first time> the hook is hit in a serialization flow, you may have it
704 return an empty list. That will signal the Storable engine to further
705 discard that hook for this class and to therefore revert to the default
706 serialization of the underlying Perl data. The hook will again be normally
707 processed in the next serialization.
709 Unless you know better, serializing hook should always say:
711 sub STORABLE_freeze {
712 my ($self, $cloning) = @_;
713 return if $cloning; # Regular default serialization
717 in order to keep reasonable dclone() semantics.
719 =item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ...
721 The deserializing hook called on the object during deserialization.
722 But wait: if we're deserializing, there's no object yet... right?
724 Wrong: the Storable engine creates an empty one for you. If you know Eiffel,
725 you can view C<STORABLE_thaw> as an alternate creation routine.
727 This means the hook can be inherited like any other method, and that
728 I<obj> is your blessed reference for this particular instance.
730 The other arguments should look familiar if you know C<STORABLE_freeze>:
731 I<cloning> is true when we're part of a deep clone operation, I<serialized>
732 is the serialized string you returned to the engine in C<STORABLE_freeze>,
733 and there may be an optional list of references, in the same order you gave
734 them at serialization time, pointing to the deserialized objects (which
735 have been processed courtesy of the Storable engine).
737 When the Storable engine does not find any C<STORABLE_thaw> hook routine,
738 it tries to load the class by requiring the package dynamically (using
739 the blessed package name), and then re-attempts the lookup. If at that
740 time the hook cannot be located, the engine croaks. Note that this mechanism
741 will fail if you define several classes in the same file, but L<perlmod>
744 It is up to you to use this information to populate I<obj> the way you want.
746 Returned value: none.
748 =item C<STORABLE_attach> I<class>, I<cloning>, I<serialized>
750 While C<STORABLE_freeze> and C<STORABLE_thaw> are useful for classes where
751 each instance is independent, this mechanism has difficulty (or is
752 incompatible) with objects that exist as common process-level or
753 system-level resources, such as singleton objects, database pools, caches
756 The alternative C<STORABLE_attach> method provides a solution for these
757 shared objects. Instead of C<STORABLE_freeze> --E<gt> C<STORABLE_thaw>,
758 you implement C<STORABLE_freeze> --E<gt> C<STORABLE_attach> instead.
760 Arguments: I<class> is the class we are attaching to, I<cloning> is a flag
761 indicating whether we're in a dclone() or a regular de-serialization via
762 thaw(), and I<serialized> is the stored string for the resource object.
764 Because these resource objects are considered to be owned by the entire
765 process/system, and not the "property" of whatever is being serialized,
766 no references underneath the object should be included in the serialized
767 string. Thus, in any class that implements C<STORABLE_attach>, the
768 C<STORABLE_freeze> method cannot return any references, and C<Storable>
769 will throw an error if C<STORABLE_freeze> tries to return references.
771 All information required to "attach" back to the shared resource object
772 B<must> be contained B<only> in the C<STORABLE_freeze> return string.
773 Otherwise, C<STORABLE_freeze> behaves as normal for C<STORABLE_attach>
776 Because C<STORABLE_attach> is passed the class (rather than an object),
777 it also returns the object directly, rather than modifying the passed
780 Returned value: object of type C<class>
786 Predicates are not exportable. They must be called by explicitly prefixing
787 them with the Storable package name.
791 =item C<Storable::last_op_in_netorder>
793 The C<Storable::last_op_in_netorder()> predicate will tell you whether
794 network order was used in the last store or retrieve operation. If you
795 don't know how to use this, just forget about it.
797 =item C<Storable::is_storing>
799 Returns true if within a store operation (via STORABLE_freeze hook).
801 =item C<Storable::is_retrieving>
803 Returns true if within a retrieve operation (via STORABLE_thaw hook).
809 With hooks comes the ability to recurse back to the Storable engine.
810 Indeed, hooks are regular Perl code, and Storable is convenient when
811 it comes to serializing and deserializing things, so why not use it
812 to handle the serialization string?
814 There are a few things you need to know, however:
820 You can create endless loops if the things you serialize via freeze()
821 (for instance) point back to the object we're trying to serialize in
826 Shared references among objects will not stay shared: if we're serializing
827 the list of object [A, C] where both object A and C refer to the SAME object
828 B, and if there is a serializing hook in A that says freeze(B), then when
829 deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D,
830 a deep clone of B'. The topology was not preserved.
834 That's why C<STORABLE_freeze> lets you provide a list of references
835 to serialize. The engine guarantees that those will be serialized in the
836 same context as the other objects, and therefore that shared objects will
839 In the above [A, C] example, the C<STORABLE_freeze> hook could return:
841 ("something", $self->{B})
843 and the B part would be serialized by the engine. In C<STORABLE_thaw>, you
844 would get back the reference to the B' object, deserialized for you.
846 Therefore, recursion should normally be avoided, but is nonetheless supported.
850 There is a Clone module available on CPAN which implements deep cloning
851 natively, i.e. without freezing to memory and thawing the result. It is
852 aimed to replace Storable's dclone() some day. However, it does not currently
853 support Storable hooks to redefine the way deep cloning is performed.
855 =head1 Storable magic
857 Yes, there's a lot of that :-) But more precisely, in UNIX systems
858 there's a utility called C<file>, which recognizes data files based on
859 their contents (usually their first few bytes). For this to work,
860 a certain file called F<magic> needs to taught about the I<signature>
861 of the data. Where that configuration file lives depends on the UNIX
862 flavour; often it's something like F</usr/share/misc/magic> or
863 F</etc/magic>. Your system administrator needs to do the updating of
864 the F<magic> file. The necessary signature information is output to
865 STDOUT by invoking Storable::show_file_magic(). Note that the GNU
866 implementation of the C<file> utility, version 3.38 or later,
867 is expected to contain support for recognising Storable files
868 out-of-the-box, in addition to other kinds of Perl files.
870 You can also use the following functions to extract the file header
871 information from Storable images:
875 =item $info = Storable::file_magic( $filename )
877 If the given file is a Storable image return a hash describing it. If
878 the file is readable, but not a Storable image return C<undef>. If
879 the file does not exist or is unreadable then croak.
881 The hash returned has the following elements:
887 This returns the file format version. It is a string like "2.7".
889 Note that this version number is not the same as the version number of
890 the Storable module itself. For instance Storable v0.7 create files
891 in format v2.0 and Storable v2.15 create files in format v2.7. The
892 file format version number only increment when additional features
893 that would confuse older versions of the module are added.
895 Files older than v2.0 will have the one of the version numbers "-1",
896 "0" or "1". No minor number was used at that time.
900 This returns the file format version as number. It is a string like
901 "2.007". This value is suitable for numeric comparisons.
903 The constant function C<Storable::BIN_VERSION_NV> returns a comparable
904 number that represent the highest file version number that this
905 version of Storable fully support (but see discussion of
906 C<$Storable::accept_future_minor> above). The constant
907 C<Storable::BIN_WRITE_VERSION_NV> function returns what file version
908 is written and might be less than C<Storable::BIN_VERSION_NV> in some
911 =item C<major>, C<minor>
913 This also returns the file format version. If the version is "2.7"
914 then major would be 2 and minor would be 7. The minor element is
915 missing for when major is less than 2.
919 The is the number of bytes that the Storable header occupies.
923 This is TRUE if the image store data in network order. This means
924 that it was created with nstore() or similar.
928 This is only present when C<netorder> is FALSE. It is the
929 $Config{byteorder} string of the perl that created this image. It is
930 a string like "1234" (32 bit little endian) or "87654321" (64 bit big
931 endian). This must match the current perl for the image to be
932 readable by Storable.
934 =item C<intsize>, C<longsize>, C<ptrsize>, C<nvsize>
936 These are only present when C<netorder> is FALSE. These are the sizes of
937 various C datatypes of the perl that created this image. These must
938 match the current perl for the image to be readable by Storable.
940 The C<nvsize> element is only present for file format v2.2 and
945 The name of the file.
949 =item $info = Storable::read_magic( $buffer )
951 =item $info = Storable::read_magic( $buffer, $must_be_file )
953 The $buffer should be a Storable image or the first few bytes of it.
954 If $buffer starts with a Storable header, then a hash describing the
955 image is returned, otherwise C<undef> is returned.
957 The hash has the same structure as the one returned by
958 Storable::file_magic(). The C<file> element is true if the image is a
961 If the $must_be_file argument is provided and is TRUE, then return
962 C<undef> unless the image looks like it belongs to a file dump.
964 The maximum size of a Storable header is currently 21 bytes. If the
965 provided $buffer is only the first part of a Storable image it should
966 at least be this long to ensure that read_magic() will recognize it as
973 Here are some code samples showing a possible usage of Storable:
975 use Storable qw(store retrieve freeze thaw dclone);
977 %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);
979 store(\%color, 'mycolors') or die "Can't store %a in mycolors!\n";
981 $colref = retrieve('mycolors');
982 die "Unable to retrieve from mycolors!\n" unless defined $colref;
983 printf "Blue is still %lf\n", $colref->{'Blue'};
985 $colref2 = dclone(\%color);
987 $str = freeze(\%color);
988 printf "Serialization of %%color is %d bytes long.\n", length($str);
989 $colref3 = thaw($str);
991 which prints (on my machine):
993 Blue is still 0.100000
994 Serialization of %color is 102 bytes long.
996 Serialization of CODE references and deserialization in a safe
1001 use Storable qw(freeze thaw);
1004 my $safe = new Safe;
1005 # because of opcodes used in "use strict":
1006 $safe->permit(qw(:default require));
1007 local $Storable::Deparse = 1;
1008 local $Storable::Eval = sub { $safe->reval($_[0]) };
1009 my $serialized = freeze(sub { 42 });
1010 my $code = thaw($serialized);
1015 =for example_testing
1016 is( $code->(), 42 );
1020 If you're using references as keys within your hash tables, you're bound
1021 to be disappointed when retrieving your data. Indeed, Perl stringifies
1022 references used as hash table keys. If you later wish to access the
1023 items via another reference stringification (i.e. using the same
1024 reference that was used for the key originally to record the value into
1025 the hash table), it will work because both references stringify to the
1028 It won't work across a sequence of C<store> and C<retrieve> operations,
1029 however, because the addresses in the retrieved objects, which are
1030 part of the stringified references, will probably differ from the
1031 original addresses. The topology of your structure is preserved,
1032 but not hidden semantics like those.
1034 On platforms where it matters, be sure to call C<binmode()> on the
1035 descriptors that you pass to Storable functions.
1037 Storing data canonically that contains large hashes can be
1038 significantly slower than storing the same data normally, as
1039 temporary arrays to hold the keys for each hash have to be allocated,
1040 populated, sorted and freed. Some tests have shown a halving of the
1041 speed of storing -- the exact penalty will depend on the complexity of
1042 your data. There is no slowdown on retrieval.
1046 You can't store GLOB, FORMLINE, etc.... If you can define semantics
1047 for those operations, feel free to enhance Storable so that it can
1050 The store functions will C<croak> if they run into such references
1051 unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that
1052 case, the fatal message is turned in a warning and some
1053 meaningless string is stored instead.
1055 Setting C<$Storable::canonical> may not yield frozen strings that
1056 compare equal due to possible stringification of numbers. When the
1057 string version of a scalar exists, it is the form stored; therefore,
1058 if you happen to use your numbers as strings between two freezing
1059 operations on the same data structures, you will get different
1062 When storing doubles in network order, their value is stored as text.
1063 However, you should also not expect non-numeric floating-point values
1064 such as infinity and "not a number" to pass successfully through a
1065 nstore()/retrieve() pair.
1067 As Storable neither knows nor cares about character sets (although it
1068 does know that characters may be more than eight bits wide), any difference
1069 in the interpretation of character codes between a host and a target
1070 system is your problem. In particular, if host and target use different
1071 code points to represent the characters used in the text representation
1072 of floating-point numbers, you will not be able be able to exchange
1073 floating-point data, even with nstore().
1075 C<Storable::drop_utf8> is a blunt tool. There is no facility either to
1076 return B<all> strings as utf8 sequences, or to attempt to convert utf8
1077 data back to 8 bit and C<croak()> if the conversion fails.
1079 Prior to Storable 2.01, no distinction was made between signed and
1080 unsigned integers on storing. By default Storable prefers to store a
1081 scalars string representation (if it has one) so this would only cause
1082 problems when storing large unsigned integers that had never been converted
1083 to string or floating point. In other words values that had been generated
1084 by integer operations such as logic ops and then not used in any string or
1085 arithmetic context before storing.
1087 =head2 64 bit data in perl 5.6.0 and 5.6.1
1089 This section only applies to you if you have existing data written out
1090 by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which
1091 has been configured with 64 bit integer support (not the default)
1092 If you got a precompiled perl, rather than running Configure to build
1093 your own perl from source, then it almost certainly does not affect you,
1094 and you can stop reading now (unless you're curious). If you're using perl
1095 on Windows it does not affect you.
1097 Storable writes a file header which contains the sizes of various C
1098 language types for the C compiler that built Storable (when not writing in
1099 network order), and will refuse to load files written by a Storable not
1100 on the same (or compatible) architecture. This check and a check on
1101 machine byteorder is needed because the size of various fields in the file
1102 are given by the sizes of the C language types, and so files written on
1103 different architectures are incompatible. This is done for increased speed.
1104 (When writing in network order, all fields are written out as standard
1105 lengths, which allows full interworking, but takes longer to read and write)
1107 Perl 5.6.x introduced the ability to optional configure the perl interpreter
1108 to use C's C<long long> type to allow scalars to store 64 bit integers on 32
1109 bit systems. However, due to the way the Perl configuration system
1110 generated the C configuration files on non-Windows platforms, and the way
1111 Storable generates its header, nothing in the Storable file header reflected
1112 whether the perl writing was using 32 or 64 bit integers, despite the fact
1113 that Storable was storing some data differently in the file. Hence Storable
1114 running on perl with 64 bit integers will read the header from a file
1115 written by a 32 bit perl, not realise that the data is actually in a subtly
1116 incompatible format, and then go horribly wrong (possibly crashing) if it
1117 encountered a stored integer. This is a design failure.
1119 Storable has now been changed to write out and read in a file header with
1120 information about the size of integers. It's impossible to detect whether
1121 an old file being read in was written with 32 or 64 bit integers (they have
1122 the same header) so it's impossible to automatically switch to a correct
1123 backwards compatibility mode. Hence this Storable defaults to the new,
1126 What this means is that if you have data written by Storable 1.x running
1127 on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux
1128 then by default this Storable will refuse to read it, giving the error
1129 I<Byte order is not compatible>. If you have such data then you you
1130 should set C<$Storable::interwork_56_64bit> to a true value to make this
1131 Storable read and write files with the old header. You should also
1132 migrate your data, or any older perl you are communicating with, to this
1133 current version of Storable.
1135 If you don't have data written with specific configuration of perl described
1136 above, then you do not and should not do anything. Don't set the flag -
1137 not only will Storable on an identically configured perl refuse to load them,
1138 but Storable a differently configured perl will load them believing them
1139 to be correct for it, and then may well fail or crash part way through
1144 Thank you to (in chronological order):
1146 Jarkko Hietaniemi <jhi@iki.fi>
1147 Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
1148 Benjamin A. Holzman <bah@ecnvantage.com>
1149 Andrew Ford <A.Ford@ford-mason.co.uk>
1150 Gisle Aas <gisle@aas.no>
1151 Jeff Gresham <gresham_jeffrey@jpmorgan.com>
1152 Murray Nesbitt <murray@activestate.com>
1153 Marc Lehmann <pcg@opengroup.org>
1154 Justin Banks <justinb@wamnet.com>
1155 Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!)
1156 Salvador Ortiz Garcia <sog@msg.com.mx>
1157 Dominic Dunlop <domo@computer.org>
1158 Erik Haugan <erik@solbors.no>
1160 for their bug reports, suggestions and contributions.
1162 Benjamin Holzman contributed the tied variable support, Andrew Ford
1163 contributed the canonical order for hashes, and Gisle Aas fixed
1164 a few misunderstandings of mine regarding the perl internals,
1165 and optimized the emission of "tags" in the output streams by
1166 simply counting the objects instead of tagging them (leading to
1167 a binary incompatibility for the Storable image starting at version
1168 0.6--older images are, of course, still properly understood).
1169 Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading
1170 and references to tied items support.
1174 Storable was written by Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
1175 Maintenance is now done by the perl5-porters F<E<lt>perl5-porters@perl.orgE<gt>>
1177 Please e-mail us with problems, bug fixes, comments and complaints,
1178 although if you have complements you should send them to Raphael.
1179 Please don't e-mail Raphael with problems, as he no longer works on
1180 Storable, and your message will be delayed while he forwards it to us.