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