.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::FcntlLock::Pure 3pm"
.TH File::FcntlLock::Pure 3pm 2024-03-07 "perl v5.38.2" "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::FcntlLock \- File locking with fcntl(2)
.PP
This text also documents the following sub\-packages:
.IP File::FcntlLock::XS 2
.IX Item "File::FcntlLock::XS"
.PD 0
.IP File::FcntlLock::Pure 2
.IX Item "File::FcntlLock::Pure"
.IP File::FcntlLock::Inline 2
.IX Item "File::FcntlLock::Inline"
.PD
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use File::FcntlLock;
\&
\&  my $fs = new File::FcntlLock;
\&  $fs\->l_type( F_RDLCK );
\&  $fs\->l_whence( SEEK_CUR );
\&  $fs\->l_start( 100 );
\&  $fs\->l_len( 123 );
\&
\&  open my $fh, \*(Aq<\*(Aq, \*(Aqfile_name\*(Aq or die "Can\*(Aqt open file: $!\en";
\&  $fs\->lock( $fh, F_SETLK )
\&      or print "Locking failed: " . $fs\->error . "\en";
\&  $fs\->l_type( F_UNLCK );
\&  $fs\->lock( $fh, F_SETLK )
\&      or print "Unlocking failed: " . $fs\->error . "\en";
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
File locking in Perl is usually done using the \f(CW\*(C`flock\*(C'\fR function.
Unfortunately, this only allows locks on whole files and is often
implemented in terms of the \fBflock\fR\|(2) system function which has
some shortcomings (especially concerning locks on remotely mounted
file systems) and slightly different behaviour than \fBfcntl\fR\|(2).
.PP
Using this module file locking via \fBfcntl\fR\|(2) can be done (obviously,
this restricts the use of the module to systems that have a \fBfcntl\fR\|(2)
system call). Before a file (or parts of a file) can be locked, an
object simulating a flock structure, containing information in a
binary format to be passed to \fBfcntl\fR\|(2) for locking requests, must
be created and its properties set. Afterwards, by calling the \fBlock()\fR
method a lock can be set and removed or it can be determined if and which
process currently holds the lock.
.PP
File::FcntlLock (or its alias File::FcntlLock::XS) uses a shared library,
build during installation, to call the \fBfcntl\fR\|(2) system function directly.
If this is unsuitable there are two alternatives, File::FcntlLock::Pure and
File::FcntlLock::Inline. Both call the Perl \f(CW\*(C`fcntl\*(C'\fR function instead and
use Perl code to assemble and disassemble the structure. For this at some
time the (system-dependent) binary layout of the flock structure must
have been determined via a program written in C. The difference between
File::FcntlLock::Pure and File::FcntlLock::Inline is that for the former
this happened when the package is installed while for the latter it is
done each time the package is loaded (e.g., with \f(CW\*(C`use\*(C'\fR). Thus, for
File::FcntlLock::Inline to work a C compiler must be available. There
are some minor differences in the functionality and the behaviour on
passing the method for locking invalid arguments to be described below.
.SS "Creating objects"
.IX Subsection "Creating objects"
.ie n .IP new() 4
.el .IP \f(CWnew()\fR 4
.IX Item "new()"
To create a new object, representing a flock structure, call \fBnew()\fR:
.Sp
.Vb 1
\&  $fs = new File::FcntlLock;
.Ve
.Sp
The object has a number of properties, reflecting the members of the
flock structure to be passed to \fBfcntl\fR\|(2) (see below). Per default
on object creation the l_type property is set to \f(CW\*(C`F_RDLCK\*(C'\fR,
l_whence to \f(CW\*(C`SEEK_SET\*(C'\fR, and both l_start and l_len to 0,
i.e., the settings for a read lock on the whole file.
.Sp
These defaults can be overruled by passing the \fBnew()\fR method a set
of key-value pairs to initialize the objects properties, e.g. use
.Sp
.Vb 4
\&  $fs = new File::FcntlLock( l_type   => F_WRLCK,
\&                             l_whence => SEEK_SET,
\&                             l_start  => 0,
\&                             l_len    => 100 );
.Ve
.Sp
if you intend to obtain a write lock for the first 100 bytes of a file.
.SS "Object properties"
.IX Subsection "Object properties"
Once the object simulating the flock structure has been created
the following methods allow to query and, in most cases, to also
modify its properties.
.ie n .IP l_type() 4
.el .IP \f(CWl_type()\fR 4
.IX Item "l_type()"
If called without an argument the method returns the current setting
of the lock type, otherwise the lock type is set to the argument's value
which must be either \f(CW\*(C`F_RDLCK\*(C'\fR, \f(CW\*(C`F_WRLCK\*(C'\fR or \f(CW\*(C`F_UNLCK\*(C'\fR (for read lock,
write lock or unlock).
.ie n .IP l_whence() 4
.el .IP \f(CWl_whence()\fR 4
.IX Item "l_whence()"
This method sets, when called with an argument, the l_whence
property of the flock object, determining if the l_start value
is relative to the start of the file, to the current position in
the file or to the end of the file. These values are \f(CW\*(C`SEEK_SET\*(C'\fR,
\&\f(CW\*(C`SEEK_CUR\*(C'\fR and \f(CW\*(C`SEEK_END\*(C'\fR (also see the man page for \fBlseek\fR\|(2)).
If called with no argument the current value of the property is
returned.
.ie n .IP l_start() 4
.el .IP \f(CWl_start()\fR 4
.IX Item "l_start()"
Queries or sets the start position (offset) of the lock in the file
according to the mode selected by the l_whence member. See also
the man page for \fBlseek\fR\|(2).
.ie n .IP l_len() 4
.el .IP \f(CWl_len()\fR 4
.IX Item "l_len()"
Queries or sets the length of the region (in bytes) in the file to
be locked. A value of 0 is interpreted to mean a lock, starting at
\&\f(CW\*(C`l_start\*(C'\fR, to the end of the file. E.g., a lock obtained with
l_whence set to \f(CW\*(C`SEEK_SET\*(C'\fR and both l_start and l_len set
to 0 locks the complete file.
.Sp
According to SUSv3 support for negative values for l_len are
permitted, resulting in a lock ranging from \f(CW\*(C`l_start+l_len\*(C'\fR up to
and including \f(CW\*(C`l_start\-1\*(C'\fR. But not all systems support negative
values for l_len and will return an error when you try to obtain
such a lock, so please read the \fBfcntl\fR\|(2) man page of the system
carefully for details.
.ie n .IP l_pid() 4
.el .IP \f(CWl_pid()\fR 4
.IX Item "l_pid()"
If a call of the \fBlock()\fR method with \f(CW\*(C`F_GETLK\*(C'\fR indicates that
another process is holding the lock (in which case the l_type
property will be either \f(CW\*(C`F_WRLCK\*(C'\fR or \f(CW\*(C`F_RDLCK\*(C'\fR) a call of the
\&\fBl_pid()\fR method returns the PID of the process holding the lock.
This method does not accept any arguments.
.SS Locking
.IX Subsection "Locking"
After having set up the object representing a flock structure one
can then try to obtain a lock, release it or determine the current
holder of the lock by invoking the \fBlock()\fR method:
.ie n .IP lock() 4
.el .IP \f(CWlock()\fR 4
.IX Item "lock()"
This method expects two arguments. The first one is a file handle
(or typeglob). File::FcntlLock, and thus File::FcntlLock::XS (\fBbut
neither\fR File::FcntlLock::Pure \fBnor\fR File::FcntlLock::Inline), also
accepts a "raw" integer file descriptor. The second argument is a
flag indicating the action to be taken. So call it as in
.Sp
.Vb 1
\&  $fs\->lock( $fh, F_SETLK );
.Ve
.Sp
There are three values that can be used as the second argument:
.RS 4
.ie n .IP """F_SETLK""" 4
.el .IP \f(CWF_SETLK\fR 4
.IX Item "F_SETLK"
With \f(CW\*(C`F_SETLK\*(C'\fR the \fBlock()\fR method tries to obtain a lock (when
l_type is set to either \f(CW\*(C`F_WRLCK\*(C'\fR or \f(CW\*(C`F_RDLCK\*(C'\fR) or releases it
(if l_type is set to \f(CW\*(C`F_UNLCK\*(C'\fR). If an attempt is made to obtain
a lock but a lock is already being held by some other process the
method returns \f(CW\*(C`undef\*(C'\fR and \f(CW\*(C`errno\*(C'\fR is set to \f(CW\*(C`EACCESS\*(C'\fR or
\&\f(CW\*(C`EAGAIN\*(C'\fR (please see the the man page for \fBfcntl\fR\|(2) for more
details).
.ie n .IP """F_SETLKW""" 4
.el .IP \f(CWF_SETLKW\fR 4
.IX Item "F_SETLKW"
is similar to \f(CW\*(C`F_SETLK\*(C'\fR, but instead of returning an error if the
lock can't be obtained immediately it puts the calling process to
sleep, i.e., it blocks, until the lock is obtained at some later
time. If a signal is received while waiting for the lock the
method returns \f(CW\*(C`undef\*(C'\fR and \f(CW\*(C`errno\*(C'\fR is set to \f(CW\*(C`EINTR\*(C'\fR.
.ie n .IP """F_GETLK""" 4
.el .IP \f(CWF_GETLK\fR 4
.IX Item "F_GETLK"
With \f(CW\*(C`F_GETLK\*(C'\fR the \fBlock()\fR method determines if and which process
currently is holding the lock.  If there's no other lock the l_type
property will be set to \f(CW\*(C`F_UNLCK\*(C'\fR. Otherwise the flock structure object
is set to the values that would prevent us from obtaining a lock. There
may be several processes that keep us from getting a lock, including
some that themselves are blocked waiting to obtain a lock. \f(CW\*(C`F_GETLK\*(C'\fR
will only make details of one of these processes visible, and one has
no control over which process this is.
.RE
.RS 4
.Sp
On success the \fBlock()\fR method returns the string "0 but true",
i.e., a value that is true in boolean but 0 in numeric context. If
the method fails (as indicated by an \f(CW\*(C`undef\*(C'\fR return value) you can
either immediately evaluate the error number (using $!, \f(CW$ERRNO\fR or
\&\f(CW$OS_ERROR\fR) or check for it via the methods discussed below at some
later time.
.RE
.SS "Error handling"
.IX Subsection "Error handling"
There are minor differences between File::FcntlLock on the one hand
and File::FcntlLock::Pure and File::FcntlLock::Inline on the other,
due to the first calling the system function \fBfcntl\fR\|(2) directly
while the latter two invoke the Perl \f(CW\*(C`fcntl\*(C'\fR function. Perl's
\&\f(CW\*(C`fcntl\*(C'\fR function already returns a Perl error on some types of
invalid arguments. In contrast File::FcntlLock passes them on to the
\&\fBfcntl\fR\|(2) system call and then returns the systems response to the
caller.
.PP
There are three methods for obtaining information about the
reason the a call of the \fBlock()\fR method failed:
.ie n .IP lock_errno() 4
.el .IP \f(CWlock_errno()\fR 4
.IX Item "lock_errno()"
Returns the \f(CW\*(C`errno\*(C'\fR error number from the latest call of \fBlock()\fR.
If the last call did not result in an error \f(CW\*(C`undef\*(C'\fR is returned.
.ie n .IP error() 4
.el .IP \f(CWerror()\fR 4
.IX Item "error()"
Returns a short description of the error that happened during the
latest call of \fBlock()\fR. Please take the messages with a grain of
salt, they represent what SUSv3 (IEEE 1003.1\-2001) and the Linux,
TRUE64, OpenBSD3 and Solaris8 man pages tell what the error numbers
mean. There could be differences (and additional error numbers) on
other systems. If there was no error the method returns \f(CW\*(C`undef\*(C'\fR.
.ie n .IP system_error() 4
.el .IP \f(CWsystem_error()\fR 4
.IX Item "system_error()"
While the \fBerror()\fR method tries to return a string with some direct
relevance to the locking operation (i.e., "File or segment already
locked by other process(es)" instead of "Permission denied") this method
returns the "normal" system error message associated with \f(CW\*(C`errno\*(C'\fR. The
method returns \f(CW\*(C`undef\*(C'\fR if there was no error.
.SS EXPORT
.IX Subsection "EXPORT"
The package exports the following constants:
.IP "F_GETLK F_SETLK F_SETLKW" 2
.IX Item "F_GETLK F_SETLK F_SETLKW"
.PD 0
.IP "F_RDLCK F_WRLCK F_UNLCK" 2
.IX Item "F_RDLCK F_WRLCK F_UNLCK"
.IP "SEEK_SET SEEK_CUR SEEK_END" 2
.IX Item "SEEK_SET SEEK_CUR SEEK_END"
.PD
.SH INCOMPATIBILITIES
.IX Header "INCOMPATIBILITIES"
Obviously, this module requires that there's a \fBfcntl\fR\|(2) system
call. Note also that under certain circumstances the File::FcntlLock::Pure
and File::FcntlLock::Inline modules may not have been installed. This
happens on 32\-bit systems that use 64\-bit integers in their flock
structure but where the installed Perl version doesn't support the 'q'
format for its \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR functions.
.SH CREDITS
.IX Header "CREDITS"
Thanks to Mark Jason Dominus and Benjamin Goldberg for helpful discussions,
code examples and encouragement. Glenn Herteg pointed out several problems
and also helped improve the documentation. Julian Moreno Patino helped
correcting the documentation and pointed out problems arising on GNU Hurd
which seems to have only very rudimentary support for locking with
\&\fBfcntl\fR\|(2). Niko Tyni and Guillem Jover encouraged and helped with
implementing alternatives to an XS-only approach which hopefully will
make the module more useful under certain circumstances.
.SH AUTHOR
.IX Header "AUTHOR"
Jens Thoms Toerring <jt@toerring.de>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBfcntl\fR\|(2), \fBlseek\fR\|(2).
.SH LICENSE
.IX Header "LICENSE"
This library is free software. You can redistribute it and/or modify it
under the same terms as Perl itself.