git.maemo.org Git - dh-make-perl/blob - dev/arm/libio-stringy-perl/io-stringy-2.110/debian/libio-stringy-perl/usr/share/perl5/IO/AtomicFile.pm

   1 package IO::AtomicFile;
   2
   3 ### DOCUMENTATION AT BOTTOM OF FILE
   4
   5 # Be strict:
   6 use strict;
   7
   8 # External modules:
   9 use IO::File;
  10
  11
  12 #------------------------------
  13 #
  14 # GLOBALS...
  15 #
  16 #------------------------------
  17 use vars qw($VERSION @ISA);
  18
  19 # The package version, both in 1.23 style *and* usable by MakeMaker:
  20 $VERSION = "2.110";
  21
  22 # Inheritance:
  23 @ISA = qw(IO::File);
  24
  25
  26 #------------------------------
  27 # new ARGS...
  28 #------------------------------
  29 # Class method, constructor.
  30 # Any arguments are sent to open().
  31 #
  32 sub new {
  33     my $class = shift;
  34     my $self = $class->SUPER::new();
  35     ${*$self}{'io_atomicfile_suffix'} = '';
  36     $self->open(@_) if @_;
  37     $self;
  38 }
  39
  40 #------------------------------
  41 # DESTROY
  42 #------------------------------
  43 # Destructor.
  44 #
  45 sub DESTROY {
  46     shift->close(1);   ### like close, but raises fatal exception on failure
  47 }
  48
  49 #------------------------------
  50 # open PATH, MODE
  51 #------------------------------
  52 # Class/instance method.
  53 #
  54 sub open {
  55     my ($self, $path, $mode) = @_;
  56     ref($self) or $self = $self->new;    ### now we have an instance!
  57
  58     ### Create tmp path, and remember this info:
  59     my $temp = "${path}..TMP" . ${*$self}{'io_atomicfile_suffix'};
  60     ${*$self}{'io_atomicfile_temp'} = $temp;
  61     ${*$self}{'io_atomicfile_path'} = $path;
  62
  63     ### Open the file!  Returns filehandle on success, for use as a constructor:
  64     $self->SUPER::open($temp, $mode) ? $self : undef;
  65 }
  66
  67 #------------------------------
  68 # _closed [YESNO]
  69 #------------------------------
  70 # Instance method, private.
  71 # Are we already closed?  Argument sets new value, returns previous one.
  72 #
  73 sub _closed {
  74     my $self = shift;
  75     my $oldval = ${*$self}{'io_atomicfile_closed'};
  76     ${*$self}{'io_atomicfile_closed'} = shift if @_;
  77     $oldval;
  78 }
  79
  80 #------------------------------
  81 # close
  82 #------------------------------
  83 # Instance method.
  84 # Close the handle, and rename the temp file to its final name.
  85 #
  86 sub close {
  87     my ($self, $die) = @_;
  88     unless ($self->_closed(1)) {             ### sentinel...
  89         if ($self->SUPER::close()) {
  90                 rename(${*$self}{'io_atomicfile_temp'},
  91                        ${*$self}{'io_atomicfile_path'})
  92                     or ($die ? die "close (rename) atomic file: $!\n" : return undef);
  93         } else {
  94                 $die ? die "close atomic file: $!\n" : return undef;
  95         }
  96     }
  97     1;
  98 }
  99
 100 #------------------------------
 101 # delete
 102 #------------------------------
 103 # Instance method.
 104 # Close the handle, and delete the temp file.
 105 #
 106 sub delete {
 107     my $self = shift;
 108     unless ($self->_closed(1)) {             ### sentinel...
 109         $self->SUPER::close();
 110         return unlink(${*$self}{'io_atomicfile_temp'});
 111     }
 112     1;
 113 }
 114
 115 #------------------------------
 116 # detach
 117 #------------------------------
 118 # Instance method.
 119 # Close the handle, but DO NOT delete the temp file.
 120 #
 121 sub detach {
 122     my $self = shift;
 123     $self->SUPER::close() unless ($self->_closed(1));
 124     1;
 125 }
 126
 127 #------------------------------
 128 1;
 129 __END__
 130
 131
 132 =head1 NAME
 133
 134 IO::AtomicFile - write a file which is updated atomically
 135
 136
 137 =head1 SYNOPSIS
 138
 139     use IO::AtomicFile;
 140
 141     ### Write a temp file, and have it install itself when closed:
 142     my $FH = IO::AtomicFile->open("bar.dat", "w");
 143     print $FH "Hello!\n";
 144     $FH->close || die "couldn't install atomic file: $!";
 145
 146     ### Write a temp file, but delete it before it gets installed:
 147     my $FH = IO::AtomicFile->open("bar.dat", "w");
 148     print $FH "Hello!\n";
 149     $FH->delete;
 150
 151     ### Write a temp file, but neither install it nor delete it:
 152     my $FH = IO::AtomicFile->open("bar.dat", "w");
 153     print $FH "Hello!\n";
 154     $FH->detach;
 155
 156
 157 =head1 DESCRIPTION
 158
 159 This module is intended for people who need to update files
 160 reliably in the face of unexpected program termination.
 161
 162 For example, you generally don't want to be halfway in the middle of
 163 writing I</etc/passwd> and have your program terminate!  Even
 164 the act of writing a single scalar to a filehandle is I<not> atomic.
 165
 166 But this module gives you true atomic updates, via rename().
 167 When you open a file I</foo/bar.dat> via this module, you are I<actually>
 168 opening a temporary file I</foo/bar.dat..TMP>, and writing your
 169 output there.   The act of closing this file (either explicitly
 170 via close(), or implicitly via the destruction of the object)
 171 will cause rename() to be called... therefore, from the point
 172 of view of the outside world, the file's contents are updated
 173 in a single time quantum.
 174
 175 To ensure that problems do not go undetected, the "close" method
 176 done by the destructor will raise a fatal exception if the rename()
 177 fails.  The explicit close() just returns undef.
 178
 179 You can also decide at any point to trash the file you've been
 180 building.
 181
 182
 183 =head1 AUTHOR
 184
 185 =head2 Primary Maintainer
 186
 187 David F. Skoll (F<dfs@roaringpenguin.com>).
 188
 189 =head2 Original Author
 190
 191 Eryq (F<eryq@zeegee.com>).
 192 President, ZeeGee Software Inc (F<http://www.zeegee.com>).
 193
 194
 195 =head1 REVISION
 196
 197 $Revision: 1.2 $
 198
 199 =cut