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