2 * Copyright (c) 2009, 2010 Zmanda, Inc. All Rights Reserved.
4 * This program is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 as published
6 * by the Free Software Foundation.
8 * This program is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
18 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
25 Amanda::Header - Amanda-specific headers prepended to dump files
30 my $hdr = Amanda::Header->new();
31 $hdr->{type} = $Amanda::Header::F_DUMPFILE;
32 $hdr->{name} = "localhost";
33 $hdr->{disk} = "/home";
35 # make a string suitable for use in a dumpfile (NUL-padded)
36 my $block = $hdr->to_string(32768, 32768);
38 # parse a string into a header
39 $hdr = Amanda::Header->from_string($block);
41 print "Working on: ", $hdr->summary(), "\n";
45 Note that, due to the vagaries of SWIG wrapping, headers actually have
46 class C<Amanda::Header::Header>.
48 The constructor creates a new, blank header, which will need at least
49 some of its attributes set before being used. These are set just like
50 any hashref-based object:
52 $hdr->{'dumplevel'} = 13;
54 To construct a new object from a bytestring (as read from the
55 beginning of a dumpfile), use
57 Amanda::Header->from_string($data);
59 To convert a header object into a bytestring, use the C<to_string(min,
60 max)> method. This method takes a minimum and maximum size. If the
61 header is smaller than the minimum size, it is padded with NUL bytes;
62 if it would be larger than the maximum size, the method returns
65 The C<summary> method returns a single-line summary of the header, with
68 As a debugging utility, the C<debug_dump> method dumps the contents of
69 the object to the debug log.
71 To compare a header to a list of dumpspecs (see L<Amanda::Cmdline>), use
73 if ($hdr->matches_dumpspecs([@dumpspecs])) { ... }
75 which is really a call to C<Amanda::Cmdline::header_matches_dumpspecs>.
77 A header object has the following keys:
86 name hostname (F_DUMPFILE) or label (F_TAPESTART)
103 totalparts (-1 == UNKNOWN)
107 C<type> is one of the following constants, which are availble for
108 import in the tag C<:constants>:
120 Some of the header fields are interrelated. The following restrictions apply.
126 C<comp_suffix> is set if and only if C<compressed> is true; the suffix "N" is
127 reserved and cannot be used.
131 C<encrypt_suffix> is set if and only if C<encrypted> is true; the suffix "N" is
132 reserved and cannot be used.
136 If C<totalparts> is not -1, then C<partnum> must be less than or equal to
137 C<totalparts>. Neither parameter can be zero. These parameters are only
138 recorded in a C<F_SPLIT_DUMPFILE> header.
142 The C<blocksize> is intended for the user's convenience only. It is written to
143 the header string, but not parsed on return. C<from_string> will always return
144 a header with blocksize=0.
148 Like C<blocksize>, C<recover_cmd>, C<uncompress_cmd> and C<decrypt_cmd> are
149 intended for the user's convenience noly. The C<uncompress_cmd> and
150 C<decrypt_cmd>, if specified, must end with C<|> (the shell pipe character).
151 Neither can be nonempty unless C<recover_cmd> is also nonempty. When parsing a
152 header with only two commands from a string, it is ambiguous whether the first
153 string is for decryption or uncompression, and this package assumes