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 .BR \-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 umask has
  20 .BR w .
  21 .SH OPTIONS
  22 .TP
  23 .B \-w
  24 Wait for the lock to be available.
  25 .TP
  26 .B \-f
  27 Fail (printing a message to stderr and exiting 255) if the lock cannot
  28 be acquired immediately because another process has it.
  29 .TP
  30 .B \-q
  31 Silently do nothing (ie, exit 0 instead of executing the specified
  32 process) if the lock cannot be acquired immediately because another
  33 process has it.
  34 .SH STALE LOCKS
  35 The locking protocol used does not suffer from stale locks.  If the
  36 lock cannot be acquired, one or more running processes must currently
  37 hold the lock; if the lock needs to be freed those processes should be
  38 killed.
  39 .PP
  40 Under no circumstances should `stale lock cleaner' cron jobs, or the
  41 like, be instituted.  In systems where a great many locks may exist,
  42 old lockfiles may be removed from cron but only if each lock is
  43 acquired before the lockfile is removed, for example with
  44 .IP
  45 .B with-lock-ex -q
  46 .I lockfile
  47 .B rm
  48 .I lockfile
  49 .SH DEADLOCKS
  50 There is no deadlock detection.  In a system with several locks, a
  51 lock hierarchy should be established, such that for every pair of
  52 locks
  53 .I A
  54 and
  55 .I B
  56 which a process might lock simultaneously, either
  57 .IR A > B
  58 or
  59 .IR B > A
  60 where the relation > is transitive and noncyclic.
  61 .PP
  62 Then, for any two locks
  63 .I X
  64 and
  65 .I Y
  66 with
  67 .IR X > Y
  68 it is forbidden to acquire
  69 .I X
  70 while holding
  71 .IR Y .
  72 Instead, acquire
  73 .I X
  74 first, or release
  75 .I Y
  76 before (re)acquiring
  77 .I X
  78 and
  79 .I Y
  80 in that order.
  81 .PP
  82 (There are more complicated ways of avoiding deadlocks, but a lock
  83 hierarchy is simple to understand and implement.  If it does not meet
  84 your needs, consult the literature.)
  85 .SH LOCKING PROTOCOL
  86 The locking protocol used by
  87 .B with-lock-ex
  88 is as follows:
  89 .PP
  90 The lock is held by a process (or group of processes) which holds an
  91 fcntl exclusive lock on the first byte of the plain file which has the
  92 specified name.  A holder of the lock (and only a holder of the lock)
  93 may delete the file or change the inode to which the name refers, and
  94 as soon as it does so it ceases to hold the lock.
  95 .PP
  96 Any process may create the file if it does not exist.  There is no
  97 need for the file to contain any actual data.  Indeed, actually using
  98 the file for data storage is strongly disrecommended, as this will
  99 foreclose most strategies for reliable update.  Use a separate
 100 lockfile instead.
 101 .PP
 102 Ability to obtain the lock corresponds to write permission on the file
 103 (and of course permission to create the  file, if it does not already
 104 exist).  However, processes with only read permission on the file can
 105 prevent the lock being acquired at all; therefore lockfiles should not
 106 usually be world-readable.
 107 .PP
 108 When a (group of) processes wishes to acquire the lock, it should open
 109 the file
 110 (with
 111 .BR O_CREAT )
 112 and lock it with
 113 .BR fcntl (2)
 114 .BR F_RWLCK ,
 115 operation
 116 .B F_SETLK
 117 or
 118 .BR F_SETLKW .
 119 If this succeeds it should fstat the file descriptor it has, and the
 120 file by its path.  If the device and inode match then the lock has
 121 been acquired and remains acquired until that group of processes
 122 changes which file the name refers to, deletes the file, or releases
 123 the fcntl lock.  If they do not then another process acquired the lock
 124 and deleted the file in the meantime; you must now close your
 125 filedescriptor and start again.
 126 .B with-lock-ex
 127 follows this specification.
 128 .PP
 129 Note that
 130 .BR flock (2)
 131 is a different kind of lock to
 132 .BR fcntl (2).
 133 .B with-lock-ex
 134 uses
 135 .BR fcntl .
 136 .SH AUTHOR
 137 This Manual page was written by Matthew Vernon <matthew@debian.org>
 138 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
 139 may be used by anyone.
 140 .SH COPYRIGHT
 141 with-lock-ex was written by Ian Jackson <ian@chiark.greenend.org.uk>
 142 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
 143 domain.
 144 .SH "SEE ALSO"
 145 .BR fcntl (2),
 146 .BR flock (2),
 147 .BR chmod (2)