git.gag.com Git - debian/amanda/blob - perl/Amanda/Tapelist.pod

   1 /*
   2  * Copyright (c) 2009 Zmanda, Inc.  All Rights Reserved.
   3  *
   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.
   7  *
   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
  11  * for more details.
  12  *
  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
  16  *
  17  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  18  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  19  */
  20
  21 %perlcode %{
  22
  23 =head1 NAME
  24
  25 Amanda::Tapelist - manipulate the Amanda tapelist
  26
  27 =head1 SYNOPSIS
  28
  29     use Amanda::Tapelist;
  30
  31     my $tl = Amanda::Tapelist::read_tapelist("/path/to/tapefile");
  32     $tl->add_tapelabel($datestamp, $label);
  33     $tl->add_tapelabel($datestamp2, $label2, $comment);
  34     $tl->write("/path/to/tapefile");
  35
  36 =head1 OBJECT-ORIENTED INTERFACE
  37
  38 The package-level functions C<read_tapelist($filename)> and
  39 C<clear_tapelist()> both return a new tapelist object.
  40 C<read_tapelist> returns C<undef> if the tapelist does not exist.
  41 Invalid entries are silently ignored.
  42
  43 A tapelist object is a sequence of tapelist elements (referred to as TLEs in
  44 this document), sorted by datestamp from newest to oldest.  Each TLE is a hash
  45 with the following keys:
  46
  47 =over
  48
  49 =item C<position>
  50
  51 the one-based position of the TLE in the tapelist
  52
  53 =item C<datestamp>
  54
  55 the datestamp on which this was written, or "0" for an unused tape
  56
  57 =item C<reuse>
  58
  59 true if this tape can be reused when it is no longer active
  60
  61 =item C<label>
  62
  63 tape label
  64
  65 =item C<comment>
  66
  67 the comment for this tape, or undef if no comment was given
  68
  69 =back
  70
  71 The following methods are available on a tapelist object C<$tl>:
  72
  73 =over
  74
  75 =item C<lookup_tapelabel($lbl)>
  76
  77 look up and return a reference to the TLE with the given label
  78
  79 =item C<lookup_tapepos($pos)>
  80
  81 look up and return a reference to the TLE in the given position
  82
  83 =item C<lookup_tapedate($date)>
  84
  85 look up and return a reference to the TLE with the given datestamp
  86
  87 =item C<remove_tapelabel($lbl)>
  88
  89 remove the tape with the given label
  90
  91 =item C<add_tapelabel($date, $lbl, $comment)>
  92
  93 add a tape with the given date, label, and comment to the end of the
  94 tapelist, marking it reusable.
  95
  96 =item C<write($filename)>
  97
  98 write the tapelist out to C<$filename>.
  99
 100 =back
 101
 102 =head1 INTERACTION WITH C CODE
 103
 104 The C portions of Amanda treat the tapelist as a global variable,
 105 while this package treats it as an object (and can thus handle more
 106 than one tapelist simultaneously).  Every call to C<read_tapelist>
 107 fills this global variable with a copy of the tapelist, and likewise
 108 C<clear_tapelist> clears the global.  However, any changes made from
 109 Perl are not reflected in the C copy, nor are changes made by C
 110 modules reflected in the Perl copy.
 111
 112 =cut
 113
 114
 115 %}