Provided by: libfile-nfslock-perl_1.29-2_all bug

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).

METHODS

       After the $lock object is instantiated with new, as outlined above, some methods may be
       used for additional functionality.

   unlock
         $lock->unlock;

       This method may be used to explicitly release a lock that is acquired.  In most cases, it
       is not necessary to call unlock directly since it will implicitly be called when the
       object leaves whatever scope it is in.

   uncache
         $lock->uncache;
         $lock->uncache("otherfile1");
         uncache("otherfile2");

       This method is used to freshen up the contents of a file across NFS, ignoring what is
       contained in the NFS client cache.  It is always called from within the new constructor on
       the file that the lock is being attempted.  uncache may be used as either an object method
       or as a stand alone subroutine.

   fork
         my $pid = $lock->fork;
         if (!defined $pid) {
           # Fork Failed
         } elsif ($pid) {
           # Parent ...
         } else {
           # Child ...
         }

       fork() is a convenience method that acts just like the normal CORE::fork() except it
       safely ensures the lock is retained within both parent and child processes. WITHOUT this,
       then when either the parent or child process releases the lock, then the entire lock will
       be lost, allowing external processes to re-acquire a lock on the same file, even if the
       other process still has the lock object in scope. This can cause corruption since both
       processes might think they have exclusive access to the file.

   newpid
         my $pid = fork;
         if (!defined $pid) {
           # Fork Failed
         } elsif ($pid) {
           $lock->newpid;
           # Parent ...
         } else {
           $lock->newpid;
           # Child ...
         }

       The newpid() synopsis shown above is equivalent to the one used for the fork() method, but
       it's not intended to be called directly. It is called internally by the fork() method. To
       be safe, it is recommended to use $lock->fork() from now on.

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 extension 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).

REPO

       The source is now on github:

       git clone https://github.com/hookbot/File-NFSLock

BUGS

       If you spot anything, please submit a pull request on github and/or submit a ticket with
       RT: https://rt.cpan.org/Dist/Display.html?Queue=File-NFSLock

   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.  He is now the
       current maintainer.

       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/

         Copyright (C) 2002-2018,
         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.