Merge branch 'master' into squeeze

[debian/amanda] / perl / Amanda / Header.pod

diff --git a/perl/Amanda/Header.pod b/perl/Amanda/Header.pod
new file mode 100644 (file)
index 0000000..40898af
--- /dev/null
+++ b/perl/Amanda/Header.pod
@@ -0,0 +1,161 @@
+/*
+ * Copyright (c) 2009, 2010 Zmanda, Inc.  All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 as published
+ * by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+ *
+ * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
+ * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
+ */
+
+%perlcode %{
+
+=head1 NAME
+
+Amanda::Header - Amanda-specific headers prepended to dump files
+
+=head1 SYNOPSIS
+
+  # create a header
+  my $hdr = Amanda::Header->new();
+  $hdr->{type} = $Amanda::Header::F_DUMPFILE;
+  $hdr->{name} = "localhost";
+  $hdr->{disk} = "/home";
+
+  # make a string suitable for use in a dumpfile (NUL-padded)
+  my $block = $hdr->to_string(32768, 32768);
+
+  # parse a string into a header
+  $hdr = Amanda::Header->from_string($block);
+
+  print "Working on: ", $hdr->summary(), "\n";
+
+=head1 Header Objects
+
+Note that, due to the vagaries of SWIG wrapping, headers actually have
+class C<Amanda::Header::Header>.
+
+The constructor creates a new, blank header, which will need at least
+some of its attributes set before being used.  These are set just like
+any hashref-based object:
+
+ $hdr->{'dumplevel'} = 13;
+
+To construct a new object from a bytestring (as read from the
+beginning of a dumpfile), use
+
+ Amanda::Header->from_string($data);
+
+To convert a header object into a bytestring, use the C<to_string(min,
+max)> method.  This method takes a minimum and maximum size.  If the
+header is smaller than the minimum size, it is padded with NUL bytes;
+if it would be larger than the maximum size, the method returns
+C<undef>.
+
+The C<summary> method returns a single-line summary of the header, with
+no trailing newline.
+
+As a debugging utility, the C<debug_dump> method dumps the contents of
+the object to the debug log.
+
+To compare a header to a list of dumpspecs (see L<Amanda::Cmdline>), use
+
+  if ($hdr->matches_dumpspecs([@dumpspecs])) { ... }
+
+which is really a call to C<Amanda::Cmdline::header_matches_dumpspecs>.
+
+A header object has the following keys:
+
+ type
+ datestamp
+ dumplevel
+ compressed
+ encrypted
+ comp_suffix
+ encrypt_suffix
+ name               hostname (F_DUMPFILE) or label (F_TAPESTART)
+ disk
+ program
+ application
+ srvcompprog
+ clntcompprog
+ srv_encrypt
+ clnt_encrypt
+ recover_cmd
+ uncompress_cmd
+ decrypt_cmd
+ srv_decrypt_opt
+ clnt_decrypt_opt
+ cont_filename
+ dle_str
+ is_partial
+ partnum
+ totalparts         (-1 == UNKNOWN)
+ blocksize
+ orig_size
+
+C<type> is one of the following constants, which are availble for
+import in the tag C<:constants>:
+
+ F_UNKNOWN
+ F_WEIRD
+ F_TAPESTART
+ F_TAPEEND
+ F_DUMPFILE
+ F_CONT_DUMPFILE
+ F_SPLIT_DUMPFILE
+ F_EMPTY
+ F_NOOP
+
+Some of the header fields are interrelated.  The following restrictions apply.
+
+=over 4
+
+=item *
+
+C<comp_suffix> is set if and only if C<compressed> is true; the suffix "N" is
+reserved and cannot be used.
+
+=item *
+
+C<encrypt_suffix> is set if and only if C<encrypted> is true; the suffix "N" is
+reserved and cannot be used.
+
+=item *
+
+If C<totalparts> is not -1, then C<partnum> must be less than or equal to
+C<totalparts>.  Neither parameter can be zero.  These parameters are only
+recorded in a C<F_SPLIT_DUMPFILE> header.
+
+=item *
+
+The C<blocksize> is intended for the user's convenience only.  It is written to
+the header string, but not parsed on return.  C<from_string> will always return
+a header with blocksize=0.
+
+=item *
+
+Like C<blocksize>, C<recover_cmd>, C<uncompress_cmd> and C<decrypt_cmd> are
+intended for the user's convenience noly.  The C<uncompress_cmd> and
+C<decrypt_cmd>, if specified, must end with C<|> (the shell pipe character).
+Neither can be nonempty unless C<recover_cmd> is also nonempty.  When parsing a
+header with only two commands from a string, it is ambiguous whether the first
+string is for decryption or uncompression, and this package assumes
+uncompression.
+
+=back
+
+=cut
+
+
+%}