NAME
    File::Symlink::Atomic - an atomic drop-in replacement for CORE::symlink

VERSION
    version 0.002

SYNOPSIS
        use File::Symlink::Atomic;   # imports replacement symlink
        symlink "target", "name1";   # easy peasy
        symlink "bullseye", "name1"; # now atomic

DESCRIPTION
    Actually creating a symlink is not problematic, but making an existing
    one point at a new target may not be atomic on your system. For example,
    on Linux, the system does "unlink" and then "symlink". In between, no
    symlink exists. If something goes wrong, you're left with nothing.

    In your shell, you probably want to do something like:

        mkdir old-target new target # Create your targets
        ln -s old-target link       # Create your initial symlink
        # ln -sf new-target link    # NOT atomic!
        ln -s new-target link-tmp && mv -Tf link-tmp link

    Moving the symlink to the new name makes it atomic, because under the
    hood, the "mv" command does "rename", which is guaranteed to be atomic
    by POSIX
    <http://pubs.opengroup.org/onlinepubs/9699919799/functions/rename.html>.

    File::Symlink::Atomic attempts to do the same thing in Perl what the
    command shown above does for your shell.

FUNCTIONS
  symlink OLDFILE,NEWFILE
    Creates a new filename symbolically linked to the old filename. Returns
    1 for success, 0 otherwise. This drop-in replacement for "CORE::symlink"
    creates a symlink with a temporary name, then renames it to the name you
    requested - this ensures that if a symlink by the requested name already
    existed, then its target is updated atomically.

CAVEATS
    This module is not guaranteed to be portable. I have no idea what this
    will do on any platform other than Linux. Feel free to run the test
    suite to find out!

AVAILABILITY
    The project homepage is
    <http://metacpan.org/release/File-Symlink-Atomic/>.

    The latest version of this module is available from the Comprehensive
    Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
    CPAN site near you, or see
    <https://metacpan.org/module/File::Symlink::Atomic/>.

SOURCE
    The development version is on github at
    <http://github.com/doherty/File-Symlink-Atomic> and may be cloned from
    <git://github.com/doherty/File-Symlink-Atomic.git>

BUGS AND LIMITATIONS
    You can make new bug reports, and view existing ones, through the web
    interface at <https://github.com/doherty/File-Symlink-Atomic/issues>.

AUTHOR
    Mike Doherty <doherty@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 by Mike Doherty.

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

