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)

Debian                                              July 2003                                    WITH-LOCK-EX(1)