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

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