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 # to get a read only copy of the tapelist file:
32 my $tl = Amanda::Tapelist->new("/path/to/tapefile");
34 # to read/update/write the tapelist file
36 my $tl = Amanda::Tapelist->new("/path/to/tapefile", 1);
37 # modify the memory copy
38 $tl->add_tapelabel($datestamp, $label);
39 $tl->add_tapelabel($datestamp2, $label2, $comment, 1);
43 # If you already have a read only copy and want to modify it
44 # take a read only copy
45 my $tl = Amanda::Tapelist->new("/path/to/tapefile");
46 # reload and take lock
48 # modify the memory copy
49 tl->add_tapelabel($datestamp, $label);
50 $tl->add_tapelabel($datestamp2, $label2, $comment, 1);
54 =head1 OBJECT-ORIENTED INTERFACE
56 C<new> returns a hash with no C<tles> set if the tapelist does
57 not exist. C<tles> is an empty array if the tapelist is empty.
58 Invalid entries are silently ignored.
60 =head2 tapelist object
62 A tapelist object is a hash with the following keys:
68 The filename of the tapelist file.
70 =item C<filename_lock>
72 The filename of the lock file.
76 A Amanda::Util::file_lock is the file is locked.
80 A sequence of tapelist elements (referred to as TLEs in this document),
81 sorted by datestamp from newest to oldest.
85 =head2 tapelist element
87 A tapelist elementas a hash with the following keys:
93 the one-based position of the TLE in the tapelist
97 the datestamp on which this was written, or "0" for an unused tape
101 true if this tape can be reused when it is no longer active
109 the comment for this tape, or undef if no comment was given
115 The following methods are available on a tapelist object C<$tl>:
119 =item C<relod($lock)>
121 reload the tapelist file, lock it if $lock is set
123 =item C<lookup_tapelabel($lbl)>
125 look up and return a reference to the TLE with the given label
127 =item C<lookup_tapepos($pos)>
129 look up and return a reference to the TLE in the given position
131 =item C<lookup_tapedate($date)>
133 look up and return a reference to the TLE with the given datestamp
135 =item C<remove_tapelabel($lbl)>
137 remove the tape with the given label
139 =item C<add_tapelabel($date, $lbl, $comment, $reuse)>
141 add a tape with the given date, label, comment and reuse to the end of the
142 tapelist. reuse can be 1 or undef for a reusable volume, it must be 0 for
143 a no-reusable volume.
145 =item C<write()> or C<write($filename)>
147 write the tapelist out to the same file as when read or to C<$filename> if it
148 is set, remove the lock if a lock was taken
152 remove the lock if a lock was taken
154 =item C<clear_tapelist()>
156 remove all tle from the tles.
160 =head1 INTERACTION WITH C CODE
162 The C portions of Amanda treat the tapelist as a global variable,
163 while this package treats it as an object (and can thus handle more
164 than one tapelist simultaneously). Every call to C<reload>
165 fills this global variable with a copy of the tapelist, and likewise
166 C<clear_tapelist> clears the global. However, any changes made from
167 Perl are not reflected in the C copy, nor are changes made by C
168 modules reflected in the Perl copy.