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