NAME

File::lockf - Perl module interface to the lockf system call

SYNOPSIS

  use File::lockf;

DESCRIPTION

File-Lockf is an interface to the lockf system call. Perl supports the flock system call natively, but that does not acquire network locks. Perl also supports the fcntl system call, but that is somewhat ugly to use. There are other locking modules available for Perl, but none of them provided what I wanted -- a simple, clean interface to the lockf system call, without any bells or whistles getting in the way.

File-Lockf contains four functions which map directly to the four modes of lockf, and an OO wrapper class that encapulates the basic locking functionality along with an additional utility method that iteratively attempts to acquire a lock.

Lock functions

The following functions return 0 (zero) on success, and the system error number from errno on failure. They each take an open file handle as the first argument, and optionally a size parameter. Please see your system lockf man page for more details about lockf functionality on your system.

$status = File::lockf::lock(FH, size = 0)

This function maps to the F_LOCK mode of lockf.

$status = File::lockf::tlock(FH, size = 0)

This function maps to the F_TLOCK mode of lockf.

$status = File::lockf::ulock(FH, size = 0)

This function maps to the F_ULOCK mode of lockf.

$status = File::lockf::test(FH, size = 0)

This function maps to the F_TEST mode of lockf.

OO wrapper

File-Lockf also provides a simple OO wrapper class around the locking functionality, which allows you to create a lock object for a file handle and then perform lock operations with it. All of the methods return 0 (zero) on success, and the system error number from errno on failure.

$lock = new File::lockf(\*FH)

This function returns a new lock object bound to the given file handle. Note that you need to pass a reference to the file handle to the constructor, not the file handle itself.

$fh = $lock->fh()

This method returns the file handle associated with the lock object.

$status = $lock->lock(size = 0)

This method calls File::lockf::lock on the bound file handle.

$status = $lock->tlock(size = 0)

This method calls File::lockf::tlock on the bound file handle.

$status = $lock->ulock(size = 0)

This method calls File::lockf::ulock on the bound file handle.

$status = $lock->test(size = 0)

This method calls File::lockf::test on the bound file handle.

$status = $lock->slock(count = 5, delay = 2, size = 0)

This method will attempt to lock the bound file handle <count> times, sleeping <delay> seconds after each try. It will return 0 if the lock succeeded, or the system error number from errno if all attempts fail.

AUTHOR

Paul Henson <henson@acm.org>

SEE ALSO

perl(1).