WITH-LOCK-EX(1) 						 Chiark-utils-bin						   WITH-LOCK-EX(1)

NAME

       with-lock-ex - file locker

SYNOPSIS

       with-lock-ex -w|-q|-f lockfile command args ...

DESCRIPTION

       with-lock-ex  will open and lock the lockfile for writing and then feed the remainder of its arguments to exec(2); when that process termi-
       nates the fd will be closed and the file unlocked automatically by the kernel.

       If the file does not exist it is created, with permissions rw for each user class for which the umask has w.

OPTIONS

       -w     Wait for the lock to be available.

       -f     Fail (printing a message to stderr and exiting 255) if the lock cannot be acquired immediately because another process has it.

       -q     Silently do nothing (ie, exit 0 instead of executing the specified process) if the  lock	cannot	be  acquired  immediately  because
	      another process has it.

STALE LOCKS

       The  locking  protocol used does not suffer from stale locks.  If the lock cannot be acquired, one or more running processes must currently
       hold the lock; if the lock needs to be freed those processes should be killed.

       Under no circumstances should `stale lock cleaner' cron jobs, or the like, be instituted.  In systems where a great many locks  may  exist,
       old lockfiles may be removed from cron but only if each lock is acquired before the lockfile is removed, for example with

	      with-lock-ex -q lockfile rm lockfile

DEADLOCKS

       There  is no deadlock detection.  In a system with several locks, a lock hierarchy should be established, such that for every pair of locks
       A and B which a process might lock simultaneously, either A>B or B>A where the relation > is transitive and noncyclic.

       Then, for any two locks X and Y with X>Y it is forbidden to acquire X while holding Y.  Instead, acquire  X  first,  or	release  Y  before
       (re)acquiring X and Y in that order.

       (There  are  more  complicated ways of avoiding deadlocks, but a lock hierarchy is simple to understand and implement.  If it does not meet
       your needs, consult the literature.)

LOCKING PROTOCOL

       The locking protocol used by with-lock-ex is as follows:

       The lock is held by a process (or group of processes) which holds an fcntl exclusive lock on the first byte of the plain file which has the
       specified name.	A holder of the lock (and only a holder of the lock) may delete the file or change the inode to which the name refers, and
       as soon as it does so it ceases to hold the lock.

       Any process may create the file if it does not exist.  There is no need for the file to contain any actual data.   Indeed,  actually  using
       the  file for data storage is strongly disrecommended, as this will foreclose most strategies for reliable update.  Use a separate lockfile
       instead.

       Ability to obtain the lock corresponds to write permission on the file (and of course permission to  create  the   file,  if  it  does  not
       already	exist).   However, processes with only read permission on the file can prevent the lock being acquired at all; therefore lockfiles
       should not usually be world-readable.

       When a (group of) processes wishes to acquire the lock, it should open the file (with O_CREAT) and lock it with fcntl(2) F_RWLCK, operation
       F_SETLK or F_SETLKW.  If this succeeds it should fstat the file descriptor it has, and the file by its path.  If the device and inode match
       then the lock has been acquired and remains acquired until that group of processes changes which file the name refers to, deletes the file,
       or releases the fcntl lock.  If they do not then another process acquired the lock and deleted the file in the meantime; you must now close
       your filedescriptor and start again.  with-lock-ex follows this specification.

       Note that flock(2) is a different kind of lock to fcntl(2).  with-lock-ex uses fcntl.

AUTHOR

       This Manual page was written by Matthew Vernon <matthew@debian.org> and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003,  but
       may be used by anyone.

COPYRIGHT

       with-lock-ex  was written by Ian Jackson <ian@chiark.greenend.org.uk> in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
       domain.

SEE ALSO

       fcntl(2), flock(2), chmod(2)

Debian								     July 2003							   WITH-LOCK-EX(1)