| File::FcntlLock::XS(3pm) | User Contributed Perl Documentation | File::FcntlLock::XS(3pm) |
File::FcntlLock - File locking with fcntl(2)
This text also documents the following sub-packages:
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, '<', 'file_name' or die "Can't open file: $!\n";
$fs->lock( $fh, F_SETLK )
or print "Locking failed: " . $fs->error . "\n";
$fs->l_type( F_UNLCK );
$fs->lock( $fh, F_SETLK )
or print "Unlocking failed: " . $fs->error . "\n";
File locking in Perl is usually done using the "flock" function. Unfortunately, this only allows locks on whole files and is often implemented in terms of the flock(2) system function which has some shortcomings (especially concerning locks on remotely mounted file systems) and slightly different behaviour than fcntl(2).
Using this module file locking via fcntl(2) can be done (obviously, this restricts the use of the module to systems that have a fcntl(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 fcntl(2) for locking requests, must be created and its properties set. Afterwards, by calling the lock() method a lock can be set and removed or it can be determined if and which process currently holds the lock.
File::FcntlLock (or its alias File::FcntlLock::XS) uses a shared library, build during installation, to call the fcntl(2) system function directly. If this is unsuitable there are two alternatives, File::FcntlLock::Pure and File::FcntlLock::Inline. Both call the Perl "fcntl" 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 "use"). 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.
$fs = new File::FcntlLock;
The object has a number of properties, reflecting the members of the flock structure to be passed to fcntl(2) (see below). Per default on object creation the l_type property is set to "F_RDLCK", l_whence to "SEEK_SET", and both l_start and l_len to 0, i.e., the settings for a read lock on the whole file.
These defaults can be overruled by passing the new() method a set of key-value pairs to initialize the objects properties, e.g. use
$fs = new File::FcntlLock( l_type => F_WRLCK,
l_whence => SEEK_SET,
l_start => 0,
l_len => 100 );
if you intend to obtain a write lock for the first 100 bytes of a file.
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.
According to SUSv3 support for negative values for l_len are permitted, resulting in a lock ranging from "l_start+l_len" up to and including "l_start-1". 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 fcntl(2) man page of the system carefully for details.
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 lock() method:
$fs->lock( $fh, F_SETLK );
There are three values that can be used as the second argument:
On success the lock() 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 "undef" return value) you can either immediately evaluate the error number (using $!, $ERRNO or $OS_ERROR) or check for it via the methods discussed below at some later time.
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 fcntl(2) directly while the latter two invoke the Perl "fcntl" function. Perl's "fcntl" function already returns a Perl error on some types of invalid arguments. In contrast File::FcntlLock passes them on to the fcntl(2) system call and then returns the systems response to the caller.
There are three methods for obtaining information about the reason the a call of the lock() method failed:
The package exports the following constants:
Obviously, this module requires that there's a fcntl(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 "pack" and "unpack" functions.
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 fcntl(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.
Jens Thoms Toerring <jt@toerring.de>
This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.
| 2022-10-19 | perl v5.36.0 |