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)