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

   1 /*
   2  * Copyright (c) 2009-2012 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
  26 Amanda::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
  57 C<new> returns a hash with no C<tles> set if the tapelist does
  58 not exist. C<tles> is an empty array if the tapelist is empty.
  59 Invalid entries are silently ignored.
  60
  61 =head2 tapelist object
  62
  63 A 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
  81 A sequence of tapelist elements (referred to as TLEs in this document),
  82 sorted by datestamp from newest to oldest.
  83
  84 =back
  85
  86 =head2 tapelist element
  87
  88 A tapelist elementas a hash with the following keys:
  89
  90 =over
  91
  92 =item C<position>
  93
  94 the one-based position of the TLE in the tapelist
  95
  96 =item C<datestamp>
  97
  98 the datestamp on which this was written, or "0" for an unused tape
  99
 100 =item C<reuse>
 101
 102 true if this tape can be reused when it is no longer active
 103
 104 =item C<label>
 105
 106 tape label
 107
 108 =item C<comment>
 109
 110 the comment for this tape, or undef if no comment was given
 111
 112 =back
 113
 114 =head1 Method
 115
 116 The following methods are available on a tapelist object C<$tl>:
 117
 118 =over
 119
 120 =item C<relod($lock)>
 121
 122 reload the tapelist file, lock it if $lock is set
 123
 124 =item C<lookup_tapelabel($lbl)>
 125
 126 look up and return a reference to the TLE with the given label
 127
 128 =item C<lookup_tapepos($pos)>
 129
 130 look up and return a reference to the TLE in the given position
 131
 132 =item C<lookup_tapedate($date)>
 133
 134 look up and return a reference to the TLE with the given datestamp
 135
 136 =item C<remove_tapelabel($lbl)>
 137
 138 remove the tape with the given label
 139
 140 =item C<add_tapelabel($date, $lbl, $comment, $reuse)>
 141
 142 add a tape with the given date, label, comment and reuse to the end of the
 143 tapelist. reuse can be 1 or undef for a reusable volume, it must be 0 for
 144 a no-reusable volume.
 145
 146 =item C<write()> or C<write($filename)>
 147
 148 write the tapelist out to the same file as when read or to C<$filename> if it
 149 is set, remove the lock if a lock was taken
 150
 151 =item C<unlock()>
 152
 153 remove the lock if a lock was taken
 154
 155 =item C<clear_tapelist()>
 156
 157 remove all tle from the tles.
 158
 159 =back
 160
 161 =head1 INTERACTION WITH C CODE
 162
 163 The C portions of Amanda treat the tapelist as a global variable,
 164 while this package treats it as an object (and can thus handle more
 165 than one tapelist simultaneously).  Every call to C<reload>
 166 fills this global variable with a copy of the tapelist, and likewise
 167 C<clear_tapelist> clears the global.  However, any changes made from
 168 Perl are not reflected in the C copy, nor are changes made by C
 169 modules reflected in the Perl copy.
 170
 171 =cut
 172
 173
 174 %}