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:

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