NAME
    IO::Adapter::AtomicFile - atomic IO operation.

SYNOPSIS
        use IO::Adapter::AtomicFile;
        my $wh = IO::Adapter::AtomicFile->open($file);
        if (defined $wh) {
            print $wh "new/updated things ...";
            $wh->close unless $wh->error;
        }

    In "close()" runs, the $file is replaced with the new content. Updating
    is defered until "close()".

    In usual cases, you use this module in the following way.

        use FileHandle;
        use IO::Adapter::AtomicFile;

        # get read handle for $file
        my $rh = new FileHandle $file;

        # get handle to update $file
        my $wh = IO::Adapter::AtomicFile->open($file);
        if (defined $rh && defined $wh) {
            while (<$rh>) {
                print $wh "new/updated things ...";
            }
            $wh->close;
            $rh->close;
        }

    You can use this method to open $file for both read and write.

        use IO::Adapter::AtomicFile;
        my ($rh, $wh) = IO::Adapter::AtomicFile->rw_open($file);
        if (defined $rh && defined $wh) {
            while (<$rh>) {
                print $wh "new/updated things ...";
            }
            $wh->close;
            $rh->close;
        }

    To copy from $src to $dst,

        IO::Adapter::AtomicFile->copy($src, $dst) || croak("fail to copy");

DESCRIPTION
    library to wrap atomic IO operations. The "atomic" feature is based on
    rename(2) system call.

METHODS
  new()
    The ordinary constructor. The request is forwarded to SUPER CLASS's
    new().

  open(file[, mode])
    open "file" with "mode". If "mode" is not specified, open "file" with
    writable mode by default.

    Actually this method opens a new temporary file for write. So to write
    this "file" is to write the temporary file. When close() method
    sucesses, the file is replaced with this temporary file.

  rw_open(file[, mode])
    return the file descriptor for both to read and write "file". This is a
    wrapper for "open()" method described above for conveninece.

  close()
    close the file. After the file is closed, the file is renamed to the
    original file name.

  copy(src, dst)
    copy from "src" file to "dst" file in atomic way by using
    "IO::Adapter::AtomicFile::rw_open".

  error()
    return the error.

  rollback()
    stop the operation and remove the temporary file to back to the first
    state.

CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2001,2002,2003,2004,2005 Ken'ichi Fukamachi

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

HISTORY
    IO::Adapter::AtomicFile first appeared in fml8 mailing list driver
    package. See "http://www.fml.org/" for more details.