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

SYNOPSIS
      use File::NFSLock (uncache);

      my $file = "somefile";

      ### set up a lock - lasts until object looses scope
      if( defined(my $lock = File::NFSLock->new($file,"NONBLOCKING")) ){
    
        ### 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
      }

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 or
    three parameters:

    Parameter 1: filename
        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.

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

          BLOCKING
          BL
          NONBLOCKING
          NB
          SHARED
          SH

        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 (shared is not
        yet implemented).

    Parameter 3: timeout (option)
        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).

TODO
        Features yet to be implemented...

        SHARED locks
            Need to allow for shared locking. This will allow for safe
            reading on files. Underway.

        Fnctl constants
            Allow for passing of Fnctl constants rather than keywords.

        Stale lock checking
            Allow for easy view into whether a lock is stale or not. Stale
            locks can occur if process is "kill -9"ed during a lock.

        Tests
            Improve the test suite.

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

        Rob B Brown (rob@roobik.com) - 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
                              rob@roobik.com
  
          This package may be distributed under the terms of either the
          GNU General Public License 
            or the
          Perl Artistic License

          All rights reserved.