NAME

SYNOPSIS

    use strict;
    use warnings;
    use feature 'say';
    use IO::AtomicFile;

    # Write a temp file, and have it install itself when closed:
    my $fh = IO::AtomicFile->open("bar.dat", "w");
    $fh->say("Hello!");
    $fh->close || die "couldn't install atomic file: $!";

    # Write a temp file, but delete it before it gets installed:
    my $fh = IO::AtomicFile->open("bar.dat", "w");
    $fh->say("Hello!");
    $fh->delete;

    # Write a temp file, but neither install it nor delete it:
    my $fh = IO::AtomicFile->open("bar.dat", "w");
    $fh->say("Hello!");
    $fh->detach;

DESCRIPTION

For example, you generally don't want to be halfway in the middle of writing /etc/passwd and have your program terminate! Even the act of writing a single scalar to a filehandle is not atomic.

But this module gives you true atomic updates, via "rename". When you open a file /foo/bar.dat via this module, you are actually opening a temporary file /foo/bar.dat..TMP, and writing your output there. The act of closing this file (either explicitly via "close", or implicitly via the destruction of the object) will cause "rename" to be called... therefore, from the point of view of the outside world, the file's contents are updated in a single time quantum.

To ensure that problems do not go undetected, the "close" method done by the destructor will raise a fatal exception if the "rename" fails. The explicit "close" just returns "undef".

You can also decide at any point to trash the file you've been building.

METHODS

    $fh->close();

    $fh->delete();

    $fh->detach();

AUTHOR

CONTRIBUTORS

COPYRIGHT & LICENSE

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