cprogs/with-lock-ex.1

   1 .TH WITH-LOCK-EX "1" "July 2003" "Debian" "Chiark-utils-bin"
   2 .SH NAME
   3 with-lock-ex \- file locker
   4 .SH SYNOPSIS
   5 .B with-lock-ex
   6 .RB [\| \-w \||\| \-q \||\| \-f \|]
   7 .I lockfile command
   8 .IR args \ \|.\|.\|.
   9 .br
  10 .SH DESCRIPTION
  11 with-lock-ex will open and lock the lockfile for writing and then feed
  12 the remainder of its arguments to
  13 .BR exec (2);
  14 when that process terminates the fd will be closed and the file
  15 unlocked automatically by the kernel.
  16 .PP
  17 If the file does not exist it is created, with permissions
  18 .B rw
  19 for each user class for which the default umask has
  20 .BR w .
  21 .SH OPTIONS
  22 .TP
  23 .B \-w
  24 wait for the lock
  25 .TP
  26 .B \-f
  27 fail if the lock cannot be acquired
  28 .TP
  29 .B \-q
  30 silently do nothing (ie, exit 0 instead of executing the specified
  31 process) if the lock cannot be acquired
  32 .SH STALE LOCKS
  33 The locking protocol used does not suffer from stale locks.  If the
  34 lock cannot be acquired, one or more running processes must currently
  35 hold the lock; if the lock needs to be freed those processes should be
  36 killed.
  37 .PP
  38 Under no circumstances should `stale lock cleaner' cron jobs, or the
  39 like, be instituted.  In systems where a great many locks may exist,
  40 old lockfiles may be removed from cron but only if each lock is
  41 acquired before the lockfile is removed, for example with
  42 .IP
  43 .B with-lock-ex -q
  44 .I lockfile
  45 .B rm
  46 .I lockfile
  47 .SH DEADLOCKS
  48 There is no deadlock detection.  In a system with several locks, a
  49 lock hierarchy should be established, such that for every pair of
  50 locks
  51 .I A
  52 and
  53 .I B
  54 which a process might lock simultaneously, either
  55 .IR A > B
  56 or
  57 .IR B > A
  58 where the relation > is transitive and noncyclic.
  59 .SH LOCKING PROTOCOL
  60 The locking protocol used by
  61 .B with-lock-ex
  62 is as follows:
  63 .PP
  64 The lock is held by a process (or group of processes) which holds an
  65 fcntl exclusive lock on the first byte of the plain file which has the
  66 specified name.  A holder of the lock (and only a holder of the lock)
  67 may delete the file or change the inode to which the name refers, and
  68 as soon as it does so it ceases to hold the lock.
  69 .PP
  70 Any process may create the file if it does not exist.  There is no
  71 need for the file to contain any actual data.  Indeed, actually using
  72 the file for data storage is strongly disrecommended, as this will
  73 foreclose most strategies for reliable update.  Use a separate
  74 lockfile instead.
  75 .PP
  76 Ability to obtain the lock corresponds to write permission on the file
  77 (and of course permission to create the  file, if it does not already
  78 exist).  However, processes with only read permission on the file can
  79 prevent the lock being acquired at all; therefore lockfiles should not
  80 usually be world-readable.
  81 .PP
  82 When a (group of) processes wishes to acquire the lock, it should open
  83 the file
  84 (with
  85 .BR O_CREAT )
  86 and lock it with
  87 .BR fcntl (2)
  88 .BR F_RWLCK ,
  89 operation
  90 .B F_SETLK
  91 or
  92 .BR F_SETLKW .
  93 If this succeeds it should fstat the file descriptor it has, and the
  94 file by its path.  If the device and inode match then the lock has
  95 been acquired and remains acquired until that group of processes
  96 changes which file the name refers to, deletes the file, or releases
  97 the fcntl lock.  If they do not then another process acquired the lock
  98 and deleted the file in the meantime; you must now close your
  99 filedescriptor and start again.
 100 .B with-lock-ex
 101 follows this specification.
 102 .SH AUTHOR
 103 This Manual page was written by Matthew Vernon <matthew@debian.org>
 104 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
 105 may be used by anyone.
 106 .SH COPYRIGHT
 107 with-lock-ex was written by Ian Jackons <ian@chiark.greenend.org.uk>
 108 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
 109 domain.