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 terminates 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)