NAME

       File::FcntlLock - File locking with fcntl(2)

       This text also documents the following sub-packages:

       File::FcntlLock::XS
       File::FcntlLock::Pure
       File::FcntlLock::Inline

SYNOPSIS

         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";

DESCRIPTION

       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.

   Creating objects
       new()
           To create a new object, representing a flock structure, call new():

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

   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.

       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_RDLCK",
           "F_WRLCK" or "F_UNLCK" (for read lock, write lock or unlock).

       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 "SEEK_SET",
           "SEEK_CUR" and "SEEK_END" (also see the man page for lseek(2)).  If called with no
           argument the current value of the property is returned.

       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 lseek(2).

       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 "l_start", to the end of the file.
           E.g., a lock obtained with l_whence set to "SEEK_SET" and both l_start and l_len set
           to 0 locks the complete file.

           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.

       l_pid()
           If a call of the lock() method with "F_GETLK" indicates that another process is
           holding the lock (in which case the l_type property will be either "F_WRLCK" or
           "F_RDLCK") a call of the l_pid() method returns the PID of the process holding the
           lock.  This method does not accept any arguments.

   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 lock()
       method:

       lock()
           This method expects two arguments. The first one is a file handle (or typeglob).
           File::FcntlLock, and thus File::FcntlLock::XS (but neither File::FcntlLock::Pure nor
           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

             $fs->lock( $fh, F_SETLK );

           There are three values that can be used as the second argument:

           "F_SETLK"
               With "F_SETLK" the lock() method tries to obtain a lock (when l_type is set to
               either "F_WRLCK" or "F_RDLCK") or releases it (if l_type is set to "F_UNLCK"). If
               an attempt is made to obtain a lock but a lock is already being held by some other
               process the method returns "undef" and "errno" is set to "EACCESS" or "EAGAIN"
               (please see the the man page for fcntl(2) for more details).

           "F_SETLKW"
               is similar to "F_SETLK", 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 "undef" and "errno" is set to "EINTR".

           "F_GETLK"
               With "F_GETLK" the lock() 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_UNLCK". 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_GETLK" will only make details of one of these processes visible, and one
               has no control over which process this is.

           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.

   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 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:

       lock_errno()
           Returns the "errno" error number from the latest call of lock().  If the last call did
           not result in an error "undef" is returned.

       error()
           Returns a short description of the error that happened during the latest call of
           lock(). 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 "undef".

       system_error()
           While the error() 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 "errno". The method returns "undef" if there was no error.

   EXPORT
       The package exports the following constants:

       F_GETLK F_SETLK F_SETLKW
       F_RDLCK F_WRLCK F_UNLCK
       SEEK_SET SEEK_CUR SEEK_END

INCOMPATIBILITIES

       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.

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

AUTHOR

       Jens Thoms Toerring <jt@toerring.de>

SEE ALSO

       perl(1), fcntl(2), lseek(2).

LICENSE

       This library is free software. You can redistribute it and/or modify it under the same
       terms as Perl itself.