git.gag.com Git - debian/amanda/blob - perl/Amanda/Header.pod

   1 /*
   2  * Copyright (c) 2009-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   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.
   7  *
   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
  11  * for more details.
  12  *
  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
  16  *
  17  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  18  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  19  */
  20
  21 %perlcode %{
  22
  23 =head1 NAME
  24
  25 Amanda::Header - Amanda-specific headers prepended to dump files
  26
  27 =head1 SYNOPSIS
  28
  29   # create a header
  30   my $hdr = Amanda::Header->new();
  31   $hdr->{type} = $Amanda::Header::F_DUMPFILE;
  32   $hdr->{name} = "localhost";
  33   $hdr->{disk} = "/home";
  34
  35   # make a string suitable for use in a dumpfile (NUL-padded)
  36   my $block = $hdr->to_string(32768, 32768);
  37
  38   # parse a string into a header
  39   $hdr = Amanda::Header->from_string($block);
  40
  41   print "Working on: ", $hdr->summary(), "\n";
  42
  43 =head1 Header Objects
  44
  45 Note that, due to the vagaries of SWIG wrapping, headers actually have
  46 class C<Amanda::Header::Header>.
  47
  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:
  51
  52  $hdr->{'dumplevel'} = 13;
  53
  54 To construct a new object from a bytestring (as read from the
  55 beginning of a dumpfile), use
  56
  57  Amanda::Header->from_string($data);
  58
  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
  63 C<undef>.
  64
  65 The C<summary> method returns a single-line summary of the header, with
  66 no trailing newline.
  67
  68 As a debugging utility, the C<debug_dump> method dumps the contents of
  69 the object to the debug log.
  70
  71 To compare a header to a list of dumpspecs (see L<Amanda::Cmdline>), use
  72
  73   if ($hdr->matches_dumpspecs([@dumpspecs])) { ... }
  74
  75 which is really a call to C<Amanda::Cmdline::header_matches_dumpspecs>.
  76
  77 A header object has the following keys:
  78
  79  type
  80  datestamp
  81  dumplevel
  82  compressed
  83  encrypted
  84  comp_suffix
  85  encrypt_suffix
  86  name               hostname (F_DUMPFILE) or label (F_TAPESTART)
  87  disk
  88  program
  89  application
  90  srvcompprog
  91  clntcompprog
  92  srv_encrypt
  93  clnt_encrypt
  94  recover_cmd
  95  uncompress_cmd
  96  decrypt_cmd
  97  srv_decrypt_opt
  98  clnt_decrypt_opt
  99  cont_filename
 100  dle_str
 101  is_partial
 102  partnum
 103  totalparts         (-1 == UNKNOWN)
 104  blocksize
 105  orig_size
 106
 107 C<type> is one of the following constants, which are availble for
 108 import in the tag C<:constants>:
 109
 110  F_UNKNOWN
 111  F_WEIRD
 112  F_TAPESTART
 113  F_TAPEEND
 114  F_DUMPFILE
 115  F_CONT_DUMPFILE
 116  F_SPLIT_DUMPFILE
 117  F_EMPTY
 118  F_NOOP
 119
 120 Some of the header fields are interrelated.  The following restrictions apply.
 121
 122 =over 4
 123
 124 =item *
 125
 126 C<comp_suffix> is set if and only if C<compressed> is true; the suffix "N" is
 127 reserved and cannot be used.
 128
 129 =item *
 130
 131 C<encrypt_suffix> is set if and only if C<encrypted> is true; the suffix "N" is
 132 reserved and cannot be used.
 133
 134 =item *
 135
 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.
 139
 140 =item *
 141
 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.
 145
 146 =item *
 147
 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
 154 uncompression.
 155
 156 =back
 157
 158 =cut
 159
 160
 161 %}