2 * Copyright (c) 2009 Zmanda, Inc. All Rights Reserved.
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.
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
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
17 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
18 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
25 Amanda::Archive - Perl access to the amanda archive library
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);
41 # Read from an archive
42 my $archive = Amanda::Archive->new($fd, "<");
45 my ($user_data, $filenum, $filename) = @_;
47 return "foo"; # this becomes $file_data
50 my ($user_data, $file_data, $filenum, $truncated) = @_;
53 21 => [ 32768, # buffer into 32k chunks
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
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
66 user_data => [ "mydata" ], # sent to all callbacks
71 =head2 Amanda::Archive::Archive Objects
73 Note that C<< Amanda::Archive->new >> and C<<
74 Amanda::Archive::Archive->new >> are equivalent.
78 =item C<new($fd, $mode)>
80 Create a new archive for reading ("<") or writing (">") from or to
81 file C<$fd> (a file handle or integer file descriptor).
83 =item C<new_file($filename, $want_posn)>
85 Create a new C<Amanda::Archive::File> object with the given filename
86 (writing only). Equivalent to
88 Amanda::Archive::File->new($archive, $filename, $want_posn);
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.
98 See I<READING>, below.
102 Flush all buffers and close this archive. This does not close the file
107 =head2 Amanda::Archive::File Objects
111 =item C<new($archive, $filename, $want_posn)>
113 Create a new file in the given archive. See
114 C<Amanda::Archive::Archive::new_file>, above.
116 =item C<new_attr($attrid)>
118 Create a new C<Amanda::Archive::Attribute> object. Equivalent to
120 Amanda::Archive::Attr->new($file, $attrid);
124 Close this file, writing an EOF record.
128 =head2 Amanda::Archive::Attribute Objects
132 =item C<add_data($data, $eoa)>
134 Add C<$data> to this attribute, adding an EOA (end-of-attribute) bit
137 =item C<add_data_fd($fh, $eoa)>
139 Copy data from C<$fh> to this attribute, adding an EOA
140 (end-of-attribute) bit if C<$eoa> is true.
144 Close this attribute, adding an EOA bit if none has been written
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:
156 my ($user_data, $filenum, $filename) = @_;
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
168 my ($user_data, $file_data, $filenum, $truncated) = @_;
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).
177 user_data => $my_object,
179 C<user_data> gives an arbitrary value which is passed to each callback
183 my ($user_data, $filenum, $file_data, $attrid,
184 $attr_data, $data, $eoa, $truncated) = @_;
187 19 => [ 10240, sub { ... } ],
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.
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>.
206 my ($arch_fh, $basedir) = @_;
208 my $arch = Amanda::Archive->new(fileno($arch_fh), "<");
211 my ($user_data, $filenum, $filename) = @_;
212 return "$basedir/$filenum"; # becomes $file_data
215 my ($user_data, $filenum, $file_data, $attrid,
216 $attr_data, $data, $eoa, $truncated) = @_;
217 warn("file $filename attribute $attrid is truncated")
219 # store the open filehandle in $attr_data
221 open($attr_data, "$file_data.$attrid", ">")
224 print $attr_data $data;