git.gag.com Git - debian/amanda/blob - perl/Amanda/Archive.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::Archive - Perl access to the  amanda archive library
  27
  28 =head1 SYNOPSIS
  29
  30   use Amanda::Archive
  31
  32   # Write to the file descriptor or file handle $fd, and
  33   # add /etc/hosts to it
  34   my $archive = Amanda::Archive->new($fd, ">");
  35   my $file = $archive->new_file("/etc/hosts");
  36   my $attr = $file->new_attr(16);
  37   open(my $fh, "<", "/etc/hosts");
  38   $attr->add_data_fd($fh, 1);
  39   $file->close();
  40   $archive->close();
  41
  42   # Read from an archive
  43   my $archive = Amanda::Archive->new($fd, "<");
  44   $ar->read(
  45       file_start => sub {
  46           my ($user_data, $filenum, $filename) = @_;
  47           # ...
  48           return "foo"; # this becomes $file_data
  49       },
  50       file_finish => sub {
  51           my ($user_data, $file_data, $filenum, $truncated) = @_;
  52           # ...
  53       },
  54       21 => [ 32768,    # buffer into 32k chunks
  55               sub {
  56                   my ($user_data, $filenum, $file_data, $attrid,
  57                       $attr_data, $data, $eoa, $truncated) = @_;
  58                   return "pants"; # becomes the new $attr_data for
  59                                   # any subsequent fragments
  60               } ],
  61       0 => sub {        # note no buffering here; attrid 0 is "default"
  62           my ($user_data, $filenum, $file_data, $attrid,
  63               $attr_data, $data, $eoa, $truncated) = @_;
  64           return "shorts"; # becomes the new $attr_data for
  65                            # any subsequent fragments
  66       },
  67       user_data => [ "mydata" ], # sent to all callbacks
  68   );
  69
  70 =head1 WRITING
  71
  72 =head2 Amanda::Archive::Archive Objects
  73
  74 Note that C<< Amanda::Archive->new >> and C<<
  75 Amanda::Archive::Archive->new >> are equivalent.
  76
  77 =over
  78
  79 =item C<new($fd, $mode)>
  80
  81 Create a new archive for reading ("<") or writing (">") from or to
  82 file C<$fd> (a file handle or integer file descriptor).
  83
  84 =item C<new_file($filename, $want_posn)>
  85
  86 Create a new C<Amanda::Archive::File> object with the given filename
  87 (writing only).  Equivalent to
  88
  89   Amanda::Archive::File->new($archive, $filename, $want_posn);
  90
  91 if C<$want_posn> is false, then this method returns a new
  92 C<Amanda::Archive::File> object.  If C<$want_posn> is true, then it
  93 returns C<($file, $posn)> where C<$file> is the object and C<$posn> is
  94 the offset into the datastream at which this file begins.  This offset
  95 can be stored in an index and used later to seek into the file.
  96
  97 =item C<read(..)>
  98
  99 See I<READING>, below.
 100
 101 =item C<close()>
 102
 103 Flush all buffers and close this archive. This does not close the file
 104 descriptor.
 105
 106 =back
 107
 108 =head2 Amanda::Archive::File Objects
 109
 110 =over
 111
 112 =item C<new($archive, $filename, $want_posn)>
 113
 114 Create a new file in the given archive.  See
 115 C<Amanda::Archive::Archive::new_file>, above.
 116
 117 =item C<new_attr($attrid)>
 118
 119 Create a new C<Amanda::Archive::Attribute> object.  Equivalent to
 120
 121   Amanda::Archive::Attr->new($file, $attrid);
 122
 123 =item C<close()>
 124
 125 Close this file, writing an EOF record.
 126
 127 =back
 128
 129 =head2 Amanda::Archive::Attribute Objects
 130
 131 =over
 132
 133 =item C<add_data($data, $eoa)>
 134
 135 Add C<$data> to this attribute, adding an EOA (end-of-attribute) bit
 136 if C<$eoa> is true.
 137
 138 =item C<add_data_fd($fh, $eoa)>
 139
 140 Copy data from C<$fh> to this attribute, adding an EOA
 141 (end-of-attribute) bit if C<$eoa> is true.
 142
 143 =item C<close()>
 144
 145 Close this attribute, adding an EOA bit if none has been written
 146 already.
 147
 148 =back
 149
 150 =head1 READING
 151
 152 The C<Amanda::Archive::Archive> method C<read()> handles reading
 153 archives via a callback mechanism.  It takes its arguments in hash
 154 form, with the following keys:
 155
 156     file_start => sub {
 157         my ($user_data, $filenum, $filename) = @_;
 158         # ..
 159     },
 160
 161 C<file_start> gives a sub which is called for every file in the
 162 archive.  It can return an arbitrary value which will become the
 163 C<$file_data> for subsequent callbacks in this file, or the string
 164 "IGNORE" which will cause the reader to ignore all data for this file.
 165 In this case, no other callbacks will be made for the file (not even
 166 C<file_finish>).
 167
 168     file_finish => sub {
 169         my ($user_data, $file_data, $filenum, $truncated) = @_;
 170         # ..
 171     },
 172
 173 C<file_finish> gives a sub which is called when an EOF record appears.
 174 C<$file_data> comes from the return value of the C<file_start>
 175 callback.  C<$truncated> is true if the file may be missing data
 176 (e.g., when an early EOF is detected).
 177
 178     user_data => $my_object,
 179
 180 C<user_data> gives an arbitrary value which is passed to each callback
 181 as C<$user_data>.
 182
 183     13 => sub {
 184         my ($user_data, $filenum, $file_data, $attrid,
 185             $attr_data, $data, $eoa, $truncated) = @_;
 186         # ...
 187     },
 188     19 => [ 10240, sub { ... } ],
 189
 190 Any numeric key is treated as an attribute ID, and specifies the
 191 handling for that attribute.  Attribute ID zero is treated as a
 192 wildcard, and will match any attribute without an explicit handler.
 193 The handler can be specified as a sub (as for attribute ID 13 in the
 194 example above) or as an arrayref C<[$minsize, $sub]>.  In the latter
 195 case, the sub is only called when at least C<$minsize> bytes of data
 196 are available for the attribute, or at the end of the attribute data.
 197
 198 The parameters to the callback include C<$file_data>, the value
 199 returned from C<file_start>, and C<$attr_data>, which is the return
 200 value of the last invocation of this sub for this attribute.  If this
 201 is the last fragment of data for this attribute, then C<$eoa> is true.
 202 The meaning of C<$truncated> is similar to that in C<file_finish>.
 203
 204 =head2 EXAMPLE
 205
 206     sub read_to_files {
 207         my ($arch_fh, $basedir) = @_;
 208
 209         my $arch = Amanda::Archive->new(fileno($arch_fh), "<");
 210         $arch->read(
 211             file_start => sub {
 212                 my ($user_data, $filenum, $filename) = @_;
 213                 return "$basedir/$filenum"; # becomes $file_data
 214             },
 215             0 => [ 32768, sub {
 216                 my ($user_data, $filenum, $file_data, $attrid,
 217                     $attr_data, $data, $eoa, $truncated) = @_;
 218                 warn("file $filename attribute $attrid is truncated")
 219                     if ($truncated);
 220                 # store the open filehandle in $attr_data
 221                 if (!$attr_data) {
 222                     open($attr_data, "$file_data.$attrid", ">")
 223                         or die("open: $!");
 224                 }
 225                 print $attr_data $data;
 226                 if ($eoa) {
 227                     close($attr_data);
 228                 }
 229                 return $attr_data;
 230             },
 231         );
 232     }
 233
 234 =cut
 235
 236
 237 %}