NAME
    File::NFSLock - perl module to do NFS (or not) locking

SYNOPSIS
      use File::NFSLock qw(uncache);
      use Fcntl qw(LOCK_EX LOCK_NB);

      my $file = "somefile";

      ### set up a lock - lasts until object looses scope
      if (my $lock = new File::NFSLock {
        file      => $file,
        lock_type => LOCK_EX|LOCK_NB,
        blocking_timeout   => 10,      # 10 sec
        stale_lock_timeout => 30 * 60, # 30 min
      }) {

        ### OR
        ### my $lock = File::NFSLock->new($file,LOCK_EX|LOCK_NB,10,30*60);

        ### do write protected stuff on $file
        ### at this point $file is uncached from NFS (most recent)
        open(FILE, "+<$file") || die $!;

        ### or open it any way you like
        ### my $fh = IO::File->open( $file, 'w' ) || die $!

        ### update (uncache across NFS) other files
        uncache("someotherfile1");
        uncache("someotherfile2");
        # open(FILE2,"someotherfile1");

        ### unlock it
        $lock->unlock();
        ### OR
        ### undef $lock;
        ### OR let $lock go out of scope
      }else{
        die "I couldn't lock the file [$File::NFSLock::errstr]";
      }

DESCRIPTION
    Program based of concept of hard linking of files being atomic
    across NFS. This concept was mentioned in Mail::Box::Locker
    (which was originally presented in Mail::Folder::Maildir). Some
    routine flow is taken from there -- particularly the idea of
    creating a random local file, hard linking a common file to the
    local file, and then checking the nlink status. Some ideologies
    were not complete (uncache mechanism, shared locking) and some
    coding was even incorrect (wrong stat index). File::NFSLock was
    written to be light, generic, and fast.

USAGE
    Locking occurs by creating a File::NFSLock object. If the object
    is created successfully, a lock is currently in place and
    remains in place until the lock object goes out of scope (or
    calls the unlock method).

    A lock object is created by calling the new method and passing
    two to four parameters in the following manner:

      my $lock = File::NFSLock->new($file,
                                    $lock_type,
                                    $blocking_timeout,
                                    $stale_lock_timeout,
                                    );

    Additionally, parameters may be passed as a hashref:

      my $lock = File::NFSLock->new({
        file               => $file,
        lock_type          => $lock_type,
        blocking_timeout   => $blocking_timeout,
        stale_lock_timeout => $stale_lock_timeout,
      });

PARAMETERS
    Parameter 1: file
        Filename of the file upon which it is anticipated that a
        write will happen to. Locking will provide the most recent
        version (uncached) of this file upon a successful file lock.
        It is not necessary for this file to exist.

    Parameter 2: lock_type
        Lock type must be one of the following:

          BLOCKING
          BL
          EXCLUSIVE (BLOCKING)
          EX
          NONBLOCKING
          NB
          SHARED
          SH

        Or else one or more of the following joined with '|':

          Fcntl::LOCK_EX() (BLOCKING)
          Fcntl::LOCK_NB() (NONBLOCKING)
          Fcntl::LOCK_SH() (SHARED)

        Lock type determines whether the lock will be blocking, non
        blocking, or shared. Blocking locks will wait until other
        locks are removed before the process continues. Non blocking
        locks will return undef if another process currently has the
        lock. Shared will allow other process to do a shared lock at
        the same time as long as there is not already an exclusive
        lock obtained.

    Parameter 3: blocking_timeout (optional)
        Timeout is used in conjunction with a blocking timeout. If
        specified, File::NFSLock will block up to the number of
        seconds specified in timeout before returning undef (could
        not get a lock).

    Parameter 4: stale_lock_timeout (optional)
        Timeout is used to see if an existing lock file is older
        than the stale lock timeout. If do_lock fails to get a lock,
        the modified time is checked and do_lock is attempted again.
        If the stale_lock_timeout is set to low, a recursion load
        could exist so do_lock will only recurse 10 times (this is
        only a problem if the stale_lock_timeout is set too low --
        on the order of one or two seconds).

FAILURE
        On failure, a global variable, $File::NFSLock::errstr,
        should be set and should contain the cause for the failure
        to get a lock. Useful primarily for debugging.

LOCK_EXTENSION
        By default File::NFSLock will use a lock file extenstion of
        ".NFSLock". This is in a global variable
        $File::NFSLock::LOCK_EXTENSION that may be changed to suit
        other purposes (such as compatibility in mail systems).

BUGS
          Aquiring a lock within the same process always fails.

          Stale locks from abnormal termination are not detected.

  FIFO

        Locks are not necessarily obtained on a first come first
        serve basis. Not only does this not seem fair to new
        processes trying to obtain a lock, but it may cause a
        process starvation condition on heavily locked files.

  DIRECTORIES

        Locks cannot be obtained on directory nodes, nor can a
        directory node be uncached with the uncache routine because
        hard links do not work with directory nodes. Some other
        algorithm might be used to uncache a directory, but I am
        unaware of the best way to do it. The biggest use I can see
        would be to avoid NFS cache of directory modified and last
        accessed timestamps.

INSTALL
        Download and extract tarball before running these commands
        in its base directory:

          perl Makefile.PL
          make
          make test
          make install

        For RPM installation, download tarball before running these
        commands in your _topdir:

          rpm -ta SOURCES/File-NFSLock-*.tar.gz
          rpm -ih RPMS/noarch/perl-File-NFSLock-*.rpm

AUTHORS
        Paul T Seamons (paul@seamons.com) - Performed majority of
        the programming with copious amounts of input from Rob
        Brown.

        Rob B Brown (bbb@cpan.org) - In addition to helping in the
        programming, Rob Brown provided most of the core testing to
        make sure implementation worked properly.

        Also Mark Overmeer (mark@overmeer.net) - Author of
        Mail::Box::Locker, from which some key concepts for
        File::NFSLock were taken.

        Also Kevin Johnson (kjj@pobox.com) - Author of
        Mail::Folder::Maildir, from which Mark Overmeer based
        Mail::Box::Locker.

COPYRIGHT
          Copyright (C) 2001, Paul T Seamons
                              paul@seamons.com
                              http://seamons.com/

                              Rob B Brown
                              bbb@cpan.org

          This package may be distributed under the terms of either the
          GNU General Public License
            or the
          Perl Artistic License

          All rights reserved.

