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
24 use vars qw($canonical $forgive_me $VERSION);
27 *AUTOLOAD = \&AutoLoader::AUTOLOAD; # Grrr...
30 # Use of Log::Agent is optional
35 eval "use Log::Agent";
41 # They might miss :flock in Fcntl
45 if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) {
46 Fcntl->import(':flock');
56 # clone context under threads
57 Storable::init_perinterp();
60 # Can't Autoload cleanly as this clashes 8.3 with &retrieve
61 sub retrieve_fd { &fd_retrieve } # Backward compatibility
63 # By default restricted hashes are downgraded on earlier perls.
65 $Storable::downgrade_restricted = 1;
66 $Storable::accept_future_minor = 1;
71 # Use of Log::Agent is optional. If it hasn't imported these subs then
72 # Autoloader will kindly supply our fallback implementation.
84 # Determine whether locking is possible, but only when needed.
87 sub CAN_FLOCK; my $CAN_FLOCK; sub CAN_FLOCK {
88 return $CAN_FLOCK if defined $CAN_FLOCK;
89 require Config; import Config;
92 $Config{'d_fcntl_can_lock'} ||
99 # To recognize the data files of the Perl module Storable,
100 # the following lines need to be added to the local magic(5) file,
101 # usually either /usr/share/misc/magic or /etc/magic.
103 0 string perl-store perl Storable(v0.6) data
104 >4 byte >0 (net-order %d)
105 >>4 byte &01 (network-ordered)
106 >>4 byte =3 (major 1)
107 >>4 byte =2 (major 1)
109 0 string pst0 perl Storable(v0.7) data
111 >>4 byte &01 (network-ordered)
112 >>4 byte =5 (major 2)
113 >>4 byte =4 (major 2)
114 >>5 byte >0 (minor %d)
120 my $fh = new FileHandle;
121 open($fh, "<". $file) || die "Can't open '$file': $!";
123 defined(sysread($fh, my $buf, 32)) || die "Can't read from '$file': $!";
126 $file = "./$file" unless $file; # ensure TRUE value
128 return read_magic($buf, $file);
132 my($buf, $file) = @_;
135 my $buflen = length($buf);
137 if ($buf =~ s/^(pst0|perl-store)//) {
139 $info{file} = $file || 1;
142 return undef if $file;
146 return undef unless length($buf);
149 if ($magic eq "perl-store" && ord(substr($buf, 0, 1)) > 1) {
155 my $major = (ord $1) >> 1;
156 return undef if $major > 4; # sanity (assuming we never go that high)
157 $info{major} = $major;
158 $net_order = (ord $1) & 0x01;
160 return undef unless $buf =~ s/(.)//s;
162 $info{minor} = $minor;
163 $info{version} = "$major.$minor";
164 $info{version_nv} = sprintf "%d.%03d", $major, $minor;
167 $info{version} = $major;
170 $info{version_nv} ||= $info{version};
171 $info{netorder} = $net_order;
173 unless ($net_order) {
174 return undef unless $buf =~ s/(.)//s;
176 return undef unless length($buf) >= $len;
177 return undef unless $len == 4 || $len == 8; # sanity
178 @info{qw(byteorder intsize longsize ptrsize)}
179 = unpack "a${len}CCC", $buf;
180 (substr $buf, 0, $len + 3) = '';
181 if ($info{version_nv} >= 2.002) {
182 return undef unless $buf =~ s/(.)//s;
183 $info{nvsize} = ord $1;
186 $info{hdrsize} = $buflen - length($buf);
192 sprintf "%d.%03d", BIN_MAJOR(), BIN_MINOR();
195 sub BIN_WRITE_VERSION_NV {
196 sprintf "%d.%03d", BIN_MAJOR(), BIN_WRITE_MINOR();
202 # Store target object hierarchy, identified by a reference to its root.
203 # The stored object tree may later be retrieved to memory via retrieve.
204 # Returns undef if an I/O error occurred, in which case the file is
208 return _store(\&pstore, @_, 0);
214 # Same as store, but in network order.
217 return _store(\&net_pstore, @_, 0);
223 # Same as store, but flock the file first (advisory locking).
226 return _store(\&pstore, @_, 1);
232 # Same as nstore, but flock the file first (advisory locking).
235 return _store(\&net_pstore, @_, 1);
238 # Internal store to file routine
242 my ($file, $use_locking) = @_;
243 logcroak "not a reference" unless ref($self);
244 logcroak "wrong argument number" unless @_ == 2; # No @foo in arglist
247 open(FILE, ">>$file") || logcroak "can't write into $file: $!";
248 unless (&CAN_FLOCK) {
249 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
252 flock(FILE, LOCK_EX) ||
253 logcroak "can't get exclusive lock on $file: $!";
255 # Unlocking will happen when FILE is closed
257 open(FILE, ">$file") || logcroak "can't create $file: $!";
259 binmode FILE; # Archaic systems...
260 my $da = $@; # Don't mess if called from exception handler
262 # Call C routine nstore or pstore, depending on network order
263 eval { $ret = &$xsptr(*FILE, $self) };
264 # close will return true on success, so the or short-circuits, the ()
265 # expression is true, and for that case the block will only be entered
266 # if $@ is true (ie eval failed)
267 # if close fails, it returns false, $ret is altered, *that* is (also)
268 # false, so the () expression is false, !() is true, and the block is
270 if (!(close(FILE) or undef $ret) || $@) {
271 unlink($file) or warn "Can't unlink $file: $!\n";
273 logcroak $@ if $@ =~ s/\.?\n$/,/;
281 # Same as store, but perform on an already opened file descriptor instead.
282 # Returns undef if an I/O error occurred.
285 return _store_fd(\&pstore, @_);
291 # Same as store_fd, but in network order.
294 my ($self, $file) = @_;
295 return _store_fd(\&net_pstore, @_);
298 # Internal store routine on opened file descriptor
303 logcroak "not a reference" unless ref($self);
304 logcroak "too many arguments" unless @_ == 1; # No @foo in arglist
305 my $fd = fileno($file);
306 logcroak "not a valid file descriptor" unless defined $fd;
307 my $da = $@; # Don't mess if called from exception handler
309 # Call C routine nstore or pstore, depending on network order
310 eval { $ret = &$xsptr($file, $self) };
311 logcroak $@ if $@ =~ s/\.?\n$/,/;
312 local $\; print $file ''; # Autoflush the file if wanted
320 # Store oject and its hierarchy in memory and return a scalar
321 # containing the result.
324 _freeze(\&mstore, @_);
330 # Same as freeze but in network order.
333 _freeze(\&net_mstore, @_);
336 # Internal freeze routine
340 logcroak "not a reference" unless ref($self);
341 logcroak "too many arguments" unless @_ == 0; # No @foo in arglist
342 my $da = $@; # Don't mess if called from exception handler
344 # Call C routine mstore or net_mstore, depending on network order
345 eval { $ret = &$xsptr($self) };
346 logcroak $@ if $@ =~ s/\.?\n$/,/;
348 return $ret ? $ret : undef;
354 # Retrieve object hierarchy from disk, returning a reference to the root
355 # object of that tree.
364 # Same as retrieve, but with advisory locking.
370 # Internal retrieve routine
372 my ($file, $use_locking) = @_;
374 open(FILE, $file) || logcroak "can't open $file: $!";
375 binmode FILE; # Archaic systems...
377 my $da = $@; # Could be from exception handler
379 unless (&CAN_FLOCK) {
380 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
383 flock(FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!";
384 # Unlocking will happen when FILE is closed
386 eval { $self = pretrieve(*FILE) }; # Call C routine
388 logcroak $@ if $@ =~ s/\.?\n$/,/;
396 # Same as retrieve, but perform from an already opened file descriptor instead.
400 my $fd = fileno($file);
401 logcroak "not a valid file descriptor" unless defined $fd;
403 my $da = $@; # Could be from exception handler
404 eval { $self = pretrieve($file) }; # Call C routine
405 logcroak $@ if $@ =~ s/\.?\n$/,/;
413 # Recreate objects in memory from an existing frozen image created
414 # by freeze. If the frozen image passed is undef, return undef.
418 return undef unless defined $frozen;
420 my $da = $@; # Could be from exception handler
421 eval { $self = mretrieve($frozen) }; # Call C routine
422 logcroak $@ if $@ =~ s/\.?\n$/,/;
432 Storable - persistence for Perl data structures
437 store \%table, 'file';
438 $hashref = retrieve('file');
440 use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);
443 nstore \%table, 'file';
444 $hashref = retrieve('file'); # There is NO nretrieve()
446 # Storing to and retrieving from an already opened file
447 store_fd \@array, \*STDOUT;
448 nstore_fd \%table, \*STDOUT;
449 $aryref = fd_retrieve(\*SOCKET);
450 $hashref = fd_retrieve(\*SOCKET);
452 # Serializing to memory
453 $serialized = freeze \%table;
454 %table_clone = %{ thaw($serialized) };
456 # Deep (recursive) cloning
457 $cloneref = dclone($ref);
460 use Storable qw(lock_store lock_nstore lock_retrieve)
461 lock_store \%table, 'file';
462 lock_nstore \%table, 'file';
463 $hashref = lock_retrieve('file');
467 The Storable package brings persistence to your Perl data structures
468 containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be
469 conveniently stored to disk and retrieved at a later time.
471 It can be used in the regular procedural way by calling C<store> with
472 a reference to the object to be stored, along with the file name where
473 the image should be written.
475 The routine returns C<undef> for I/O problems or other internal error,
476 a true value otherwise. Serious errors are propagated as a C<die> exception.
478 To retrieve data stored to disk, use C<retrieve> with a file name.
479 The objects stored into that file are recreated into memory for you,
480 and a I<reference> to the root object is returned. In case an I/O error
481 occurs while reading, C<undef> is returned instead. Other serious
482 errors are propagated via C<die>.
484 Since storage is performed recursively, you might want to stuff references
485 to objects that share a lot of common data into a single array or hash
486 table, and then store that object. That way, when you retrieve back the
487 whole thing, the objects will continue to share what they originally shared.
489 At the cost of a slight header overhead, you may store to an already
490 opened file descriptor using the C<store_fd> routine, and retrieve
491 from a file via C<fd_retrieve>. Those names aren't imported by default,
492 so you will have to do that explicitly if you need those routines.
493 The file descriptor you supply must be already opened, for read
494 if you're going to retrieve and for write if you wish to store.
496 store_fd(\%table, *STDOUT) || die "can't store to stdout\n";
497 $hashref = fd_retrieve(*STDIN);
499 You can also store data in network order to allow easy sharing across
500 multiple platforms, or when storing on a socket known to be remotely
501 connected. The routines to call have an initial C<n> prefix for I<network>,
502 as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be
503 correctly restored so you don't have to know whether you're restoring
504 from native or network ordered data. Double values are stored stringified
505 to ensure portability as well, at the slight risk of loosing some precision
506 in the last decimals.
508 When using C<fd_retrieve>, objects are retrieved in sequence, one
509 object (i.e. one recursive tree) per associated C<store_fd>.
511 If you're more from the object-oriented camp, you can inherit from
512 Storable and directly store your objects by invoking C<store> as
513 a method. The fact that the root of the to-be-stored tree is a
514 blessed reference (i.e. an object) is special-cased so that the
515 retrieve does not provide a reference to that object but rather the
516 blessed object reference itself. (Otherwise, you'd get a reference
517 to that blessed object).
521 The Storable engine can also store data into a Perl scalar instead, to
522 later retrieve them. This is mainly used to freeze a complex structure in
523 some safe compact memory place (where it can possibly be sent to another
524 process via some IPC, since freezing the structure also serializes it in
525 effect). Later on, and maybe somewhere else, you can thaw the Perl scalar
526 out and recreate the original complex structure in memory.
528 Surprisingly, the routines to be called are named C<freeze> and C<thaw>.
529 If you wish to send out the frozen scalar to another machine, use
530 C<nfreeze> instead to get a portable image.
532 Note that freezing an object structure and immediately thawing it
533 actually achieves a deep cloning of that structure:
535 dclone(.) = thaw(freeze(.))
537 Storable provides you with a C<dclone> interface which does not create
538 that intermediary scalar but instead freezes the structure in some
539 internal memory space and then immediately thaws it out.
541 =head1 ADVISORY LOCKING
543 The C<lock_store> and C<lock_nstore> routine are equivalent to
544 C<store> and C<nstore>, except that they get an exclusive lock on
545 the file before writing. Likewise, C<lock_retrieve> does the same
546 as C<retrieve>, but also gets a shared lock on the file before reading.
548 As with any advisory locking scheme, the protection only works if you
549 systematically use C<lock_store> and C<lock_retrieve>. If one side of
550 your application uses C<store> whilst the other uses C<lock_retrieve>,
551 you will get no protection at all.
553 The internal advisory locking is implemented using Perl's flock()
554 routine. If your system does not support any form of flock(), or if
555 you share your files across NFS, you might wish to use other forms
556 of locking by using modules such as LockFile::Simple which lock a
557 file using a filesystem entry, instead of locking the file descriptor.
561 The heart of Storable is written in C for decent speed. Extra low-level
562 optimizations have been made when manipulating perl internals, to
563 sacrifice encapsulation for the benefit of greater speed.
565 =head1 CANONICAL REPRESENTATION
567 Normally, Storable stores elements of hashes in the order they are
568 stored internally by Perl, i.e. pseudo-randomly. If you set
569 C<$Storable::canonical> to some C<TRUE> value, Storable will store
570 hashes with the elements sorted by their key. This allows you to
571 compare data structures by comparing their frozen representations (or
572 even the compressed frozen representations), which can be useful for
573 creating lookup tables for complicated queries.
575 Canonical order does not imply network order; those are two orthogonal
578 =head1 CODE REFERENCES
580 Since Storable version 2.05, CODE references may be serialized with
581 the help of L<B::Deparse>. To enable this feature, set
582 C<$Storable::Deparse> to a true value. To enable deserialization,
583 C<$Storable::Eval> should be set to a true value. Be aware that
584 deserialization is done through C<eval>, which is dangerous if the
585 Storable file contains malicious data. You can set C<$Storable::Eval>
586 to a subroutine reference which would be used instead of C<eval>. See
587 below for an example using a L<Safe> compartment for deserialization
590 If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false
591 values, then the value of C<$Storable::forgive_me> (see below) is
592 respected while serializing and deserializing.
594 =head1 FORWARD COMPATIBILITY
596 This release of Storable can be used on a newer version of Perl to
597 serialize data which is not supported by earlier Perls. By default,
598 Storable will attempt to do the right thing, by C<croak()>ing if it
599 encounters data that it cannot deserialize. However, the defaults
600 can be changed as follows:
606 Perl 5.6 added support for Unicode characters with code points > 255,
607 and Perl 5.8 has full support for Unicode characters in hash keys.
608 Perl internally encodes strings with these characters using utf8, and
609 Storable serializes them as utf8. By default, if an older version of
610 Perl encounters a utf8 value it cannot represent, it will C<croak()>.
611 To change this behaviour so that Storable deserializes utf8 encoded
612 values as the string of bytes (effectively dropping the I<is_utf8> flag)
613 set C<$Storable::drop_utf8> to some C<TRUE> value. This is a form of
614 data loss, because with C<$drop_utf8> true, it becomes impossible to tell
615 whether the original data was the Unicode string, or a series of bytes
616 that happen to be valid utf8.
618 =item restricted hashes
620 Perl 5.8 adds support for restricted hashes, which have keys
621 restricted to a given set, and can have values locked to be read only.
622 By default, when Storable encounters a restricted hash on a perl
623 that doesn't support them, it will deserialize it as a normal hash,
624 silently discarding any placeholder keys and leaving the keys and
625 all values unlocked. To make Storable C<croak()> instead, set
626 C<$Storable::downgrade_restricted> to a C<FALSE> value. To restore
627 the default set it back to some C<TRUE> value.
629 =item files from future versions of Storable
631 Earlier versions of Storable would immediately croak if they encountered
632 a file with a higher internal version number than the reading Storable
633 knew about. Internal version numbers are increased each time new data
634 types (such as restricted hashes) are added to the vocabulary of the file
635 format. This meant that a newer Storable module had no way of writing a
636 file readable by an older Storable, even if the writer didn't store newer
639 This version of Storable will defer croaking until it encounters a data
640 type in the file that it does not recognize. This means that it will
641 continue to read files generated by newer Storable modules which are careful
642 in what they write out, making it easier to upgrade Storable modules in a
645 The old behaviour of immediate croaking can be re-instated by setting
646 C<$Storable::accept_future_minor> to some C<FALSE> value.
650 All these variables have no effect on a newer Perl which supports the
653 =head1 ERROR REPORTING
655 Storable uses the "exception" paradigm, in that it does not try to workaround
656 failures: if something bad happens, an exception is generated from the
657 caller's perspective (see L<Carp> and C<croak()>). Use eval {} to trap
660 When Storable croaks, it tries to report the error via the C<logcroak()>
661 routine from the C<Log::Agent> package, if it is available.
663 Normal errors are reported by having store() or retrieve() return C<undef>.
664 Such errors are usually I/O errors (or truncated stream errors at retrieval).
670 Any class may define hooks that will be called during the serialization
671 and deserialization process on objects that are instances of that class.
672 Those hooks can redefine the way serialization is performed (and therefore,
673 how the symmetrical deserialization should be conducted).
675 Since we said earlier:
677 dclone(.) = thaw(freeze(.))
679 everything we say about hooks should also hold for deep cloning. However,
680 hooks get to know whether the operation is a mere serialization, or a cloning.
682 Therefore, when serializing hooks are involved,
684 dclone(.) <> thaw(freeze(.))
686 Well, you could keep them in sync, but there's no guarantee it will always
687 hold on classes somebody else wrote. Besides, there is little to gain in
688 doing so: a serializing hook could keep only one attribute of an object,
689 which is probably not what should happen during a deep cloning of that
692 Here is the hooking interface:
696 =item C<STORABLE_freeze> I<obj>, I<cloning>
698 The serializing hook, called on the object during serialization. It can be
699 inherited, or defined in the class itself, like any other method.
701 Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating
702 whether we're in a dclone() or a regular serialization via store() or freeze().
704 Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized
705 is the serialized form to be used, and the optional $ref1, $ref2, etc... are
706 extra references that you wish to let the Storable engine serialize.
708 At deserialization time, you will be given back the same LIST, but all the
709 extra references will be pointing into the deserialized structure.
711 The B<first time> the hook is hit in a serialization flow, you may have it
712 return an empty list. That will signal the Storable engine to further
713 discard that hook for this class and to therefore revert to the default
714 serialization of the underlying Perl data. The hook will again be normally
715 processed in the next serialization.
717 Unless you know better, serializing hook should always say:
719 sub STORABLE_freeze {
720 my ($self, $cloning) = @_;
721 return if $cloning; # Regular default serialization
725 in order to keep reasonable dclone() semantics.
727 =item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ...
729 The deserializing hook called on the object during deserialization.
730 But wait: if we're deserializing, there's no object yet... right?
732 Wrong: the Storable engine creates an empty one for you. If you know Eiffel,
733 you can view C<STORABLE_thaw> as an alternate creation routine.
735 This means the hook can be inherited like any other method, and that
736 I<obj> is your blessed reference for this particular instance.
738 The other arguments should look familiar if you know C<STORABLE_freeze>:
739 I<cloning> is true when we're part of a deep clone operation, I<serialized>
740 is the serialized string you returned to the engine in C<STORABLE_freeze>,
741 and there may be an optional list of references, in the same order you gave
742 them at serialization time, pointing to the deserialized objects (which
743 have been processed courtesy of the Storable engine).
745 When the Storable engine does not find any C<STORABLE_thaw> hook routine,
746 it tries to load the class by requiring the package dynamically (using
747 the blessed package name), and then re-attempts the lookup. If at that
748 time the hook cannot be located, the engine croaks. Note that this mechanism
749 will fail if you define several classes in the same file, but L<perlmod>
752 It is up to you to use this information to populate I<obj> the way you want.
754 Returned value: none.
756 =item C<STORABLE_attach> I<class>, I<cloning>, I<serialized>
758 While C<STORABLE_freeze> and C<STORABLE_thaw> are useful for classes where
759 each instance is independent, this mechanism has difficulty (or is
760 incompatible) with objects that exist as common process-level or
761 system-level resources, such as singleton objects, database pools, caches
764 The alternative C<STORABLE_attach> method provides a solution for these
765 shared objects. Instead of C<STORABLE_freeze> --E<gt> C<STORABLE_thaw>,
766 you implement C<STORABLE_freeze> --E<gt> C<STORABLE_attach> instead.
768 Arguments: I<class> is the class we are attaching to, I<cloning> is a flag
769 indicating whether we're in a dclone() or a regular de-serialization via
770 thaw(), and I<serialized> is the stored string for the resource object.
772 Because these resource objects are considered to be owned by the entire
773 process/system, and not the "property" of whatever is being serialized,
774 no references underneath the object should be included in the serialized
775 string. Thus, in any class that implements C<STORABLE_attach>, the
776 C<STORABLE_freeze> method cannot return any references, and C<Storable>
777 will throw an error if C<STORABLE_freeze> tries to return references.
779 All information required to "attach" back to the shared resource object
780 B<must> be contained B<only> in the C<STORABLE_freeze> return string.
781 Otherwise, C<STORABLE_freeze> behaves as normal for C<STORABLE_attach>
784 Because C<STORABLE_attach> is passed the class (rather than an object),
785 it also returns the object directly, rather than modifying the passed
788 Returned value: object of type C<class>
794 Predicates are not exportable. They must be called by explicitly prefixing
795 them with the Storable package name.
799 =item C<Storable::last_op_in_netorder>
801 The C<Storable::last_op_in_netorder()> predicate will tell you whether
802 network order was used in the last store or retrieve operation. If you
803 don't know how to use this, just forget about it.
805 =item C<Storable::is_storing>
807 Returns true if within a store operation (via STORABLE_freeze hook).
809 =item C<Storable::is_retrieving>
811 Returns true if within a retrieve operation (via STORABLE_thaw hook).
817 With hooks comes the ability to recurse back to the Storable engine.
818 Indeed, hooks are regular Perl code, and Storable is convenient when
819 it comes to serializing and deserializing things, so why not use it
820 to handle the serialization string?
822 There are a few things you need to know, however:
828 You can create endless loops if the things you serialize via freeze()
829 (for instance) point back to the object we're trying to serialize in
834 Shared references among objects will not stay shared: if we're serializing
835 the list of object [A, C] where both object A and C refer to the SAME object
836 B, and if there is a serializing hook in A that says freeze(B), then when
837 deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D,
838 a deep clone of B'. The topology was not preserved.
842 That's why C<STORABLE_freeze> lets you provide a list of references
843 to serialize. The engine guarantees that those will be serialized in the
844 same context as the other objects, and therefore that shared objects will
847 In the above [A, C] example, the C<STORABLE_freeze> hook could return:
849 ("something", $self->{B})
851 and the B part would be serialized by the engine. In C<STORABLE_thaw>, you
852 would get back the reference to the B' object, deserialized for you.
854 Therefore, recursion should normally be avoided, but is nonetheless supported.
858 There is a Clone module available on CPAN which implements deep cloning
859 natively, i.e. without freezing to memory and thawing the result. It is
860 aimed to replace Storable's dclone() some day. However, it does not currently
861 support Storable hooks to redefine the way deep cloning is performed.
863 =head1 Storable magic
865 Yes, there's a lot of that :-) But more precisely, in UNIX systems
866 there's a utility called C<file>, which recognizes data files based on
867 their contents (usually their first few bytes). For this to work,
868 a certain file called F<magic> needs to taught about the I<signature>
869 of the data. Where that configuration file lives depends on the UNIX
870 flavour; often it's something like F</usr/share/misc/magic> or
871 F</etc/magic>. Your system administrator needs to do the updating of
872 the F<magic> file. The necessary signature information is output to
873 STDOUT by invoking Storable::show_file_magic(). Note that the GNU
874 implementation of the C<file> utility, version 3.38 or later,
875 is expected to contain support for recognising Storable files
876 out-of-the-box, in addition to other kinds of Perl files.
878 You can also use the following functions to extract the file header
879 information from Storable images:
883 =item $info = Storable::file_magic( $filename )
885 If the given file is a Storable image return a hash describing it. If
886 the file is readable, but not a Storable image return C<undef>. If
887 the file does not exist or is unreadable then croak.
889 The hash returned has the following elements:
895 This returns the file format version. It is a string like "2.7".
897 Note that this version number is not the same as the version number of
898 the Storable module itself. For instance Storable v0.7 create files
899 in format v2.0 and Storable v2.15 create files in format v2.7. The
900 file format version number only increment when additional features
901 that would confuse older versions of the module are added.
903 Files older than v2.0 will have the one of the version numbers "-1",
904 "0" or "1". No minor number was used at that time.
908 This returns the file format version as number. It is a string like
909 "2.007". This value is suitable for numeric comparisons.
911 The constant function C<Storable::BIN_VERSION_NV> returns a comparable
912 number that represent the highest file version number that this
913 version of Storable fully support (but see discussion of
914 C<$Storable::accept_future_minor> above). The constant
915 C<Storable::BIN_WRITE_VERSION_NV> function returns what file version
916 is written and might be less than C<Storable::BIN_VERSION_NV> in some
919 =item C<major>, C<minor>
921 This also returns the file format version. If the version is "2.7"
922 then major would be 2 and minor would be 7. The minor element is
923 missing for when major is less than 2.
927 The is the number of bytes that the Storable header occupies.
931 This is TRUE if the image store data in network order. This means
932 that it was created with nstore() or similar.
936 This is only present when C<netorder> is FALSE. It is the
937 $Config{byteorder} string of the perl that created this image. It is
938 a string like "1234" (32 bit little endian) or "87654321" (64 bit big
939 endian). This must match the current perl for the image to be
940 readable by Storable.
942 =item C<intsize>, C<longsize>, C<ptrsize>, C<nvsize>
944 These are only present when C<netorder> is FALSE. These are the sizes of
945 various C datatypes of the perl that created this image. These must
946 match the current perl for the image to be readable by Storable.
948 The C<nvsize> element is only present for file format v2.2 and
953 The name of the file.
957 =item $info = Storable::read_magic( $buffer )
959 =item $info = Storable::read_magic( $buffer, $must_be_file )
961 The $buffer should be a Storable image or the first few bytes of it.
962 If $buffer starts with a Storable header, then a hash describing the
963 image is returned, otherwise C<undef> is returned.
965 The hash has the same structure as the one returned by
966 Storable::file_magic(). The C<file> element is true if the image is a
969 If the $must_be_file argument is provided and is TRUE, then return
970 C<undef> unless the image looks like it belongs to a file dump.
972 The maximum size of a Storable header is currently 21 bytes. If the
973 provided $buffer is only the first part of a Storable image it should
974 at least be this long to ensure that read_magic() will recognize it as
981 Here are some code samples showing a possible usage of Storable:
983 use Storable qw(store retrieve freeze thaw dclone);
985 %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);
987 store(\%color, 'mycolors') or die "Can't store %a in mycolors!\n";
989 $colref = retrieve('mycolors');
990 die "Unable to retrieve from mycolors!\n" unless defined $colref;
991 printf "Blue is still %lf\n", $colref->{'Blue'};
993 $colref2 = dclone(\%color);
995 $str = freeze(\%color);
996 printf "Serialization of %%color is %d bytes long.\n", length($str);
997 $colref3 = thaw($str);
999 which prints (on my machine):
1001 Blue is still 0.100000
1002 Serialization of %color is 102 bytes long.
1004 Serialization of CODE references and deserialization in a safe
1009 use Storable qw(freeze thaw);
1012 my $safe = new Safe;
1013 # because of opcodes used in "use strict":
1014 $safe->permit(qw(:default require));
1015 local $Storable::Deparse = 1;
1016 local $Storable::Eval = sub { $safe->reval($_[0]) };
1017 my $serialized = freeze(sub { 42 });
1018 my $code = thaw($serialized);
1023 =for example_testing
1024 is( $code->(), 42 );
1028 If you're using references as keys within your hash tables, you're bound
1029 to be disappointed when retrieving your data. Indeed, Perl stringifies
1030 references used as hash table keys. If you later wish to access the
1031 items via another reference stringification (i.e. using the same
1032 reference that was used for the key originally to record the value into
1033 the hash table), it will work because both references stringify to the
1036 It won't work across a sequence of C<store> and C<retrieve> operations,
1037 however, because the addresses in the retrieved objects, which are
1038 part of the stringified references, will probably differ from the
1039 original addresses. The topology of your structure is preserved,
1040 but not hidden semantics like those.
1042 On platforms where it matters, be sure to call C<binmode()> on the
1043 descriptors that you pass to Storable functions.
1045 Storing data canonically that contains large hashes can be
1046 significantly slower than storing the same data normally, as
1047 temporary arrays to hold the keys for each hash have to be allocated,
1048 populated, sorted and freed. Some tests have shown a halving of the
1049 speed of storing -- the exact penalty will depend on the complexity of
1050 your data. There is no slowdown on retrieval.
1054 You can't store GLOB, FORMLINE, REGEXP, etc.... If you can define semantics
1055 for those operations, feel free to enhance Storable so that it can
1058 The store functions will C<croak> if they run into such references
1059 unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that
1060 case, the fatal message is turned in a warning and some
1061 meaningless string is stored instead.
1063 Setting C<$Storable::canonical> may not yield frozen strings that
1064 compare equal due to possible stringification of numbers. When the
1065 string version of a scalar exists, it is the form stored; therefore,
1066 if you happen to use your numbers as strings between two freezing
1067 operations on the same data structures, you will get different
1070 When storing doubles in network order, their value is stored as text.
1071 However, you should also not expect non-numeric floating-point values
1072 such as infinity and "not a number" to pass successfully through a
1073 nstore()/retrieve() pair.
1075 As Storable neither knows nor cares about character sets (although it
1076 does know that characters may be more than eight bits wide), any difference
1077 in the interpretation of character codes between a host and a target
1078 system is your problem. In particular, if host and target use different
1079 code points to represent the characters used in the text representation
1080 of floating-point numbers, you will not be able be able to exchange
1081 floating-point data, even with nstore().
1083 C<Storable::drop_utf8> is a blunt tool. There is no facility either to
1084 return B<all> strings as utf8 sequences, or to attempt to convert utf8
1085 data back to 8 bit and C<croak()> if the conversion fails.
1087 Prior to Storable 2.01, no distinction was made between signed and
1088 unsigned integers on storing. By default Storable prefers to store a
1089 scalars string representation (if it has one) so this would only cause
1090 problems when storing large unsigned integers that had never been converted
1091 to string or floating point. In other words values that had been generated
1092 by integer operations such as logic ops and then not used in any string or
1093 arithmetic context before storing.
1095 =head2 64 bit data in perl 5.6.0 and 5.6.1
1097 This section only applies to you if you have existing data written out
1098 by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which
1099 has been configured with 64 bit integer support (not the default)
1100 If you got a precompiled perl, rather than running Configure to build
1101 your own perl from source, then it almost certainly does not affect you,
1102 and you can stop reading now (unless you're curious). If you're using perl
1103 on Windows it does not affect you.
1105 Storable writes a file header which contains the sizes of various C
1106 language types for the C compiler that built Storable (when not writing in
1107 network order), and will refuse to load files written by a Storable not
1108 on the same (or compatible) architecture. This check and a check on
1109 machine byteorder is needed because the size of various fields in the file
1110 are given by the sizes of the C language types, and so files written on
1111 different architectures are incompatible. This is done for increased speed.
1112 (When writing in network order, all fields are written out as standard
1113 lengths, which allows full interworking, but takes longer to read and write)
1115 Perl 5.6.x introduced the ability to optional configure the perl interpreter
1116 to use C's C<long long> type to allow scalars to store 64 bit integers on 32
1117 bit systems. However, due to the way the Perl configuration system
1118 generated the C configuration files on non-Windows platforms, and the way
1119 Storable generates its header, nothing in the Storable file header reflected
1120 whether the perl writing was using 32 or 64 bit integers, despite the fact
1121 that Storable was storing some data differently in the file. Hence Storable
1122 running on perl with 64 bit integers will read the header from a file
1123 written by a 32 bit perl, not realise that the data is actually in a subtly
1124 incompatible format, and then go horribly wrong (possibly crashing) if it
1125 encountered a stored integer. This is a design failure.
1127 Storable has now been changed to write out and read in a file header with
1128 information about the size of integers. It's impossible to detect whether
1129 an old file being read in was written with 32 or 64 bit integers (they have
1130 the same header) so it's impossible to automatically switch to a correct
1131 backwards compatibility mode. Hence this Storable defaults to the new,
1134 What this means is that if you have data written by Storable 1.x running
1135 on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux
1136 then by default this Storable will refuse to read it, giving the error
1137 I<Byte order is not compatible>. If you have such data then you you
1138 should set C<$Storable::interwork_56_64bit> to a true value to make this
1139 Storable read and write files with the old header. You should also
1140 migrate your data, or any older perl you are communicating with, to this
1141 current version of Storable.
1143 If you don't have data written with specific configuration of perl described
1144 above, then you do not and should not do anything. Don't set the flag -
1145 not only will Storable on an identically configured perl refuse to load them,
1146 but Storable a differently configured perl will load them believing them
1147 to be correct for it, and then may well fail or crash part way through
1152 Thank you to (in chronological order):
1154 Jarkko Hietaniemi <jhi@iki.fi>
1155 Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
1156 Benjamin A. Holzman <bholzman@earthlink.net>
1157 Andrew Ford <A.Ford@ford-mason.co.uk>
1158 Gisle Aas <gisle@aas.no>
1159 Jeff Gresham <gresham_jeffrey@jpmorgan.com>
1160 Murray Nesbitt <murray@activestate.com>
1161 Marc Lehmann <pcg@opengroup.org>
1162 Justin Banks <justinb@wamnet.com>
1163 Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!)
1164 Salvador Ortiz Garcia <sog@msg.com.mx>
1165 Dominic Dunlop <domo@computer.org>
1166 Erik Haugan <erik@solbors.no>
1167 Benjamin A. Holzman <ben.holzman@grantstreet.com>
1169 for their bug reports, suggestions and contributions.
1171 Benjamin Holzman contributed the tied variable support, Andrew Ford
1172 contributed the canonical order for hashes, and Gisle Aas fixed
1173 a few misunderstandings of mine regarding the perl internals,
1174 and optimized the emission of "tags" in the output streams by
1175 simply counting the objects instead of tagging them (leading to
1176 a binary incompatibility for the Storable image starting at version
1177 0.6--older images are, of course, still properly understood).
1178 Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading
1179 and references to tied items support. Benjamin Holzman added a performance
1180 improvement for overloaded classes; thanks to Grant Street Group for footing
1185 Storable was written by Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
1186 Maintenance is now done by the perl5-porters F<E<lt>perl5-porters@perl.orgE<gt>>
1188 Please e-mail us with problems, bug fixes, comments and complaints,
1189 although if you have compliments you should send them to Raphael.
1190 Please don't e-mail Raphael with problems, as he no longer works on
1191 Storable, and your message will be delayed while he forwards it to us.