.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "File::NFSLock 3pm"
.TH File::NFSLock 3pm "2022-12-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::NFSLock \- perl module to do NFS (or not) locking
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  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, \*(Aqw\*(Aq ) || 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\*(Aqt lock the file [$File::NFSLock::errstr]";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Program based of concept of hard linking of files being atomic across
\&\s-1NFS.\s0  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.
.SH "USAGE"
.IX Header "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).
.PP
A lock object is created by calling the new method and passing two
to four parameters in the following manner:
.PP
.Vb 5
\&  my $lock = File::NFSLock\->new($file,
\&                                $lock_type,
\&                                $blocking_timeout,
\&                                $stale_lock_timeout,
\&                                );
.Ve
.PP
Additionally, parameters may be passed as a hashref:
.PP
.Vb 6
\&  my $lock = File::NFSLock\->new({
\&    file               => $file,
\&    lock_type          => $lock_type,
\&    blocking_timeout   => $blocking_timeout,
\&    stale_lock_timeout => $stale_lock_timeout,
\&  });
.Ve
.SH "PARAMETERS"
.IX Header "PARAMETERS"
.IP "Parameter 1: file" 4
.IX Item "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.
.IP "Parameter 2: lock_type" 4
.IX Item "Parameter 2: lock_type"
Lock type must be one of the following:
.Sp
.Vb 8
\&  BLOCKING
\&  BL
\&  EXCLUSIVE (BLOCKING)
\&  EX
\&  NONBLOCKING
\&  NB
\&  SHARED
\&  SH
.Ve
.Sp
Or else one or more of the following joined with '|':
.Sp
.Vb 3
\&  Fcntl::LOCK_EX() (BLOCKING)
\&  Fcntl::LOCK_NB() (NONBLOCKING)
\&  Fcntl::LOCK_SH() (SHARED)
.Ve
.Sp
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.
.IP "Parameter 3: blocking_timeout (optional)" 4
.IX Item "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).
.IP "Parameter 4: stale_lock_timeout (optional)" 4
.IX Item "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).
.SH "METHODS"
.IX Header "METHODS"
After the \f(CW$lock\fR object is instantiated with new,
as outlined above, some methods may be used for
additional functionality.
.SS "unlock"
.IX Subsection "unlock"
.Vb 1
\&  $lock\->unlock;
.Ve
.PP
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.
.SS "uncache"
.IX Subsection "uncache"
.Vb 3
\&  $lock\->uncache;
\&  $lock\->uncache("otherfile1");
\&  uncache("otherfile2");
.Ve
.PP
This method is used to freshen up the contents of a
file across \s-1NFS,\s0 ignoring what is contained in the
\&\s-1NFS\s0 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.
.SS "fork"
.IX Subsection "fork"
.Vb 8
\&  my $pid = $lock\->fork;
\&  if (!defined $pid) {
\&    # Fork Failed
\&  } elsif ($pid) {
\&    # Parent ...
\&  } else {
\&    # Child ...
\&  }
.Ve
.PP
\&\fBfork()\fR is a convenience method that acts just like the normal
\&\fBCORE::fork()\fR except it safely ensures the lock is retained
within both parent and child processes. \s-1WITHOUT\s0 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.
.SS "newpid"
.IX Subsection "newpid"
.Vb 10
\&  my $pid = fork;
\&  if (!defined $pid) {
\&    # Fork Failed
\&  } elsif ($pid) {
\&    $lock\->newpid;
\&    # Parent ...
\&  } else {
\&    $lock\->newpid;
\&    # Child ...
\&  }
.Ve
.PP
The \fBnewpid()\fR synopsis shown above is equivalent to the
one used for the \fBfork()\fR method, but it's not intended
to be called directly. It is called internally by the
\&\fBfork()\fR method. To be safe, it is recommended to use
\&\f(CW$lock\fR\->\fBfork()\fR from now on.
.SH "FAILURE"
.IX Header "FAILURE"
On failure, a global variable, \f(CW$File::NFSLock::errstr\fR, should be set and should
contain the cause for the failure to get a lock.  Useful primarily for debugging.
.SH "LOCK_EXTENSION"
.IX Header "LOCK_EXTENSION"
By default File::NFSLock will use a lock file extension of \*(L".NFSLock\*(R".  This is
in a global variable \f(CW$File::NFSLock::LOCK_EXTENSION\fR that may be changed to
suit other purposes (such as compatibility in mail systems).
.SH "REPO"
.IX Header "REPO"
The source is now on github:
.PP
git clone https://github.com/hookbot/File\-NFSLock
.SH "BUGS"
.IX Header "BUGS"
If you spot anything, please submit a pull request on
github and/or submit a ticket with \s-1RT:\s0
https://rt.cpan.org/Dist/Display.html?Queue=File\-NFSLock
.SS "\s-1FIFO\s0"
.IX Subsection "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.
.SS "\s-1DIRECTORIES\s0"
.IX Subsection "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 \s-1NFS\s0 cache of directory modified and last accessed
timestamps.
.SH "INSTALL"
.IX Header "INSTALL"
Download and extract tarball before running
these commands in its base directory:
.PP
.Vb 4
\&  perl Makefile.PL
\&  make
\&  make test
\&  make install
.Ve
.PP
For \s-1RPM\s0 installation, download tarball before
running these commands in your _topdir:
.PP
.Vb 2
\&  rpm \-ta SOURCES/File\-NFSLock\-*.tar.gz
\&  rpm \-ih RPMS/noarch/perl\-File\-NFSLock\-*.rpm
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Paul T Seamons (paul@seamons.com) \- Performed majority of the
programming with copious amounts of input from Rob Brown.
.PP
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.
.PP
Also Mark Overmeer (mark@overmeer.net) \- Author of Mail::Box::Locker,
from which some key concepts for File::NFSLock were taken.
.PP
Also Kevin Johnson (kjj@pobox.com) \- Author of Mail::Folder::Maildir,
from which Mark Overmeer based Mail::Box::Locker.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 4
\&  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.
.Ve