/*
- * Copyright (c) 2009 Zmanda, Inc. All Rights Reserved.
+ * Copyright (c) 2009-2012 Zmanda, Inc. All Rights Reserved.
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 as published
use Amanda::Tapelist;
- my $tl = Amanda::Tapelist::read_tapelist("/path/to/tapefile");
+ # to get a read only copy of the tapelist file:
+ my $tl = Amanda::Tapelist->new("/path/to/tapefile");
+
+ # to read/update/write the tapelist file
+ # read and take lock
+ my $tl = Amanda::Tapelist->new("/path/to/tapefile", 1);
+ # modify the memory copy
$tl->add_tapelabel($datestamp, $label);
- $tl->add_tapelabel($datestamp2, $label2, $comment);
- $tl->write("/path/to/tapefile");
+ $tl->add_tapelabel($datestamp2, $label2, $comment, 1);
+ # write it and unlock
+ $tl->write();
+
+ # If you already have a read only copy and want to modify it
+ # take a read only copy
+ my $tl = Amanda::Tapelist->new("/path/to/tapefile");
+ # reload and take lock
+ $tl->reload(1);
+ # modify the memory copy
+ tl->add_tapelabel($datestamp, $label);
+ $tl->add_tapelabel($datestamp2, $label2, $comment, 1);
+ # write it and unlock
+ $tl->write();
=head1 OBJECT-ORIENTED INTERFACE
-The package-level functions C<read_tapelist($filename)> and
-C<clear_tapelist()> both return a new tapelist object.
-C<read_tapelist> returns C<undef> if the tapelist does not exist.
+C<new> returns a hash with no C<tles> set if the tapelist does
+not exist. C<tles> is an empty array if the tapelist is empty.
Invalid entries are silently ignored.
-A tapelist object is a sequence of tapelist elements (referred to as TLEs in
-this document), sorted by datestamp from newest to oldest. Each TLE is a hash
-with the following keys:
+=head2 tapelist object
+
+A tapelist object is a hash with the following keys:
+
+=over
+
+=item C<filename>
+
+ The filename of the tapelist file.
+
+=item C<filename_lock>
+
+ The filename of the lock file.
+
+=item C<fl>
+
+ A Amanda::Util::file_lock is the file is locked.
+
+=item C<tles>
+
+A sequence of tapelist elements (referred to as TLEs in this document),
+sorted by datestamp from newest to oldest.
+
+=back
+
+=head2 tapelist element
+
+A tapelist elementas a hash with the following keys:
=over
=back
+=head1 Method
+
The following methods are available on a tapelist object C<$tl>:
=over
+=item C<relod($lock)>
+
+reload the tapelist file, lock it if $lock is set
+
=item C<lookup_tapelabel($lbl)>
look up and return a reference to the TLE with the given label
remove the tape with the given label
-=item C<add_tapelabel($date, $lbl, $comment)>
+=item C<add_tapelabel($date, $lbl, $comment, $reuse)>
+
+add a tape with the given date, label, comment and reuse to the end of the
+tapelist. reuse can be 1 or undef for a reusable volume, it must be 0 for
+a no-reusable volume.
+
+=item C<write()> or C<write($filename)>
+
+write the tapelist out to the same file as when read or to C<$filename> if it
+is set, remove the lock if a lock was taken
+
+=item C<unlock()>
-add a tape with the given date, label, and comment to the end of the
-tapelist, marking it reusable.
+remove the lock if a lock was taken
-=item C<write($filename)>
+=item C<clear_tapelist()>
-write the tapelist out to C<$filename>.
+remove all tle from the tles.
=back
The C portions of Amanda treat the tapelist as a global variable,
while this package treats it as an object (and can thus handle more
-than one tapelist simultaneously). Every call to C<read_tapelist>
+than one tapelist simultaneously). Every call to C<reload>
fills this global variable with a copy of the tapelist, and likewise
C<clear_tapelist> clears the global. However, any changes made from
Perl are not reflected in the C copy, nor are changes made by C