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::Tapelist - manipulate the Amanda tapelist
31 my $tl = Amanda::Tapelist::read_tapelist("/path/to/tapefile");
32 $tl->add_tapelabel($datestamp, $label);
33 $tl->add_tapelabel($datestamp2, $label2, $comment);
34 $tl->write("/path/to/tapefile");
36 =head1 OBJECT-ORIENTED INTERFACE
38 The package-level functions C<read_tapelist($filename)> and
39 C<clear_tapelist()> both return a new tapelist object.
40 C<read_tapelist> returns C<undef> if the tapelist does not exist.
41 Invalid entries are silently ignored.
43 A tapelist object is a sequence of tapelist elements (referred to as TLEs in
44 this document), sorted by datestamp from newest to oldest. Each TLE is a hash
45 with the following keys:
51 the one-based position of the TLE in the tapelist
55 the datestamp on which this was written, or "0" for an unused tape
59 true if this tape can be reused when it is no longer active
67 the comment for this tape, or undef if no comment was given
71 The following methods are available on a tapelist object C<$tl>:
75 =item C<lookup_tapelabel($lbl)>
77 look up and return a reference to the TLE with the given label
79 =item C<lookup_tapepos($pos)>
81 look up and return a reference to the TLE in the given position
83 =item C<lookup_tapedate($date)>
85 look up and return a reference to the TLE with the given datestamp
87 =item C<remove_tapelabel($lbl)>
89 remove the tape with the given label
91 =item C<add_tapelabel($date, $lbl, $comment)>
93 add a tape with the given date, label, and comment to the end of the
94 tapelist, marking it reusable.
96 =item C<write($filename)>
98 write the tapelist out to C<$filename>.
102 =head1 INTERACTION WITH C CODE
104 The C portions of Amanda treat the tapelist as a global variable,
105 while this package treats it as an object (and can thus handle more
106 than one tapelist simultaneously). Every call to C<read_tapelist>
107 fills this global variable with a copy of the tapelist, and likewise
108 C<clear_tapelist> clears the global. However, any changes made from
109 Perl are not reflected in the C copy, nor are changes made by C
110 modules reflected in the Perl copy.