NAME

File::Lock - Utility to lock and unlock files.

SYNOPSIS

use File::Lock;

my $result = File::Lock::lock($file); my $result = File::Lock::lock(file => $file timeout => 10, debug => 0);

my $result = File::Lock::unlock($file); my $result = File::Lock::unlock(file => $file);

my $result = File::Lock::check($file); my $result = File::Lock::check(file => $file);

DESCRIPTION

File::Lock provides a lock, unlock, and check function for working with file locks.

CONSTRUCTOR

Lock( [FILE] [,OPTIONS] );

If FILE is not given, then it may instead be passed as the file option described below.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

file - The file to lock

timeout - Number of seconds to continue trying to lock (Default: 10).

debug - Print debugging info to STDERR (0=Off, 1=On).

RETURN VALUE

Here are a list of return codes of the lock function and what they mean:

0 The file is locked.

1 The file is not found.

2 Master lock exists and is not writable

3 Could not unlink stale master lock

4 Could not fork ps

5 Could not read master lock

6 Could not write to temporary lock

7 The file is already locked.

.. and for the check function:

0 File is locked

1 File is not locked

2 permissions problems with lock files

.. and the unlock function:

0 File unlocked.

1 Couldnt unlock file

2 Couldnt unlink master lock

3 Couldnt unlink temporary lock

EXAMPLES

  use File::Lock;
  my $file = shift;
  unless(defined($file)){
    print "file to lock: ";
    chop($file=<STDIN>);
  }
  my $result = File::Lock::lock($file);
  if($result){
    print "Could not lock: ${result}\n";
  }else{
    print "$file is now locked\n";
  }
        
        # do stuff to file

  if($result = File::Lock::unlock($file)){
    print "could not unlock $file: $result\n";
  }
  exit;

CAVEATS

This utility must be used by all code that works with the file you're trying to lock. Locking with File::Lock will not keep someone from using vi and editing the file.

If you leave lock files around (from not unlocking the file before your code exits), File::Lock will try its best to determine if the lock files are stale or not. This is best effort, and may yield false positives. For example, if your code was running as pid 1234 and exited without unlocking, stale detection may fail if there is a new process running with pid 1234.

RESTRICTIONS

Locking will only remain successfull while your code is active. You can not lock a file, let your code exit, and expect the file to remain locked; doing so will result in stale lock files left behind.

lock file -> do stuff -> unlock file -> exit;

AUTHOR

<a href="http://jeremy.kister.net./">Jeremy Kister</a>