1/* 2 * Copyright (c) 2009-2013 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 26Amanda::Tapelist - manipulate the Amanda tapelist 27 28=head1 SYNOPSIS 29 30 use Amanda::Tapelist; 31 32 # to get a read only copy of the tapelist file: 33 my $tl = Amanda::Tapelist->new("/path/to/tapefile"); 34 35 # to read/update/write the tapelist file 36 # read and take lock 37 my $tl = Amanda::Tapelist->new("/path/to/tapefile", 1); 38 # modify the memory copy 39 $tl->add_tapelabel($datestamp, $label); 40 $tl->add_tapelabel($datestamp2, $label2, $comment, 1); 41 # write it and unlock 42 $tl->write(); 43 44 # If you already have a read only copy and want to modify it 45 # take a read only copy 46 my $tl = Amanda::Tapelist->new("/path/to/tapefile"); 47 # reload and take lock 48 $tl->reload(1); 49 # modify the memory copy 50 tl->add_tapelabel($datestamp, $label); 51 $tl->add_tapelabel($datestamp2, $label2, $comment, 1); 52 # write it and unlock 53 $tl->write(); 54 55=head1 OBJECT-ORIENTED INTERFACE 56 57C<new> returns a hash with no C<tles> set if the tapelist does 58not exist. C<tles> is an empty array if the tapelist is empty. 59Invalid entries are silently ignored. 60 61=head2 tapelist object 62 63A tapelist object is a hash with the following keys: 64 65=over 66 67=item C<filename> 68 69 The filename of the tapelist file. 70 71=item C<filename_lock> 72 73 The filename of the lock file. 74 75=item C<fl> 76 77 A Amanda::Util::file_lock is the file is locked. 78 79=item C<tles> 80 81A sequence of tapelist elements (referred to as TLEs in this document), 82sorted by datestamp from newest to oldest. 83 84=back 85 86=head2 tapelist element 87 88A tapelist elementas a hash with the following keys: 89 90=over 91 92=item C<position> 93 94the one-based position of the TLE in the tapelist 95 96=item C<datestamp> 97 98the datestamp on which this was written, or "0" for an unused tape 99 100=item C<reuse> 101 102true if this tape can be reused when it is no longer active 103 104=item C<label> 105 106tape label 107 108=item C<comment> 109 110the comment for this tape, or undef if no comment was given 111 112=back 113 114=head1 Method 115 116The following methods are available on a tapelist object C<$tl>: 117 118=over 119 120=item C<relod($lock)> 121 122reload the tapelist file, lock it if $lock is set 123 124=item C<lookup_tapelabel($lbl)> 125 126look up and return a reference to the TLE with the given label 127 128=item C<lookup_tapepos($pos)> 129 130look up and return a reference to the TLE in the given position 131 132=item C<lookup_tapedate($date)> 133 134look up and return a reference to the TLE with the given datestamp 135 136=item C<remove_tapelabel($lbl)> 137 138remove the tape with the given label 139 140=item C<add_tapelabel($date, $lbl, $comment, $reuse)> 141 142add a tape with the given date, label, comment and reuse to the end of the 143tapelist. reuse can be 1 or undef for a reusable volume, it must be 0 for 144a no-reusable volume. 145 146=item C<write()> or C<write($filename)> 147 148write the tapelist out to the same file as when read or to C<$filename> if it 149is set, remove the lock if a lock was taken 150 151=item C<unlock()> 152 153remove the lock if a lock was taken 154 155=item C<clear_tapelist()> 156 157remove all tle from the tles. 158 159=back 160 161=head1 INTERACTION WITH C CODE 162 163The C portions of Amanda treat the tapelist as a global variable, 164while this package treats it as an object (and can thus handle more 165than one tapelist simultaneously). Every call to C<reload> 166fills this global variable with a copy of the tapelist, and likewise 167C<clear_tapelist> clears the global. However, any changes made from 168Perl are not reflected in the C copy, nor are changes made by C 169modules reflected in the Perl copy. 170 171=cut 172 173 174%} 175