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