# 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/](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/](http://www.perl.com/CPAN/) to find a CPAN
site near you, or see [https://metacpan.org/module/File::Symlink::Atomic/](https://metacpan.org/module/File::Symlink::Atomic/).

# SOURCE

The development version is on github at [http://github.com/doherty/File-Symlink-Atomic](http://github.com/doherty/File-Symlink-Atomic)
and may be cloned from [git://github.com/doherty/File-Symlink-Atomic.git](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](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.
