Imported Upstream version 3.2.0

[debian/amanda] / perl / Amanda / Tapelist.pod

diff --git a/perl/Amanda/Tapelist.pod b/perl/Amanda/Tapelist.pod
index 0fe8b7389c2e321ddab6cc15dce5fd8f595977bb..1d266705c4a83f1695713187f97960159d0e10b3 100644 (file)
--- a/perl/Amanda/Tapelist.pod
+++ b/perl/Amanda/Tapelist.pod
@@ -28,21 +28,63 @@ Amanda::Tapelist - manipulate the Amanda tapelist
 
     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
 
@@ -68,10 +110,16 @@ the comment for this tape, or undef if no comment was given
 
 =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
@@ -88,14 +136,24 @@ look up and return a reference to the TLE with the given datestamp
 
 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
 
@@ -103,7 +161,7 @@ write the tapelist out to C<$filename>.
 
 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