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 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 .PP
  60 Then, for any two locks
  61 .I X
  62 and
  63 .I Y
  64 with
  65 .IR X > Y
  66 it is forbidden to acquire
  67 .I X
  68 while holding
  69 .IR Y .
  70 Instead, acquire
  71 .I X
  72 first, or release
  73 .I Y
  74 before (re)acquiring
  75 .I X
  76 and
  77 .I Y
  78 in that order.
  79 .PP
  80 (There are more complicated ways of avoiding deadlocks, but a lock
  81 hierarchy is simple to understand and implement.  If it does not meet
  82 your needs, consult the literature.)
  83 .SH LOCKING PROTOCOL
  84 The locking protocol used by
  85 .B with-lock-ex
  86 is as follows:
  87 .PP
  88 The lock is held by a process (or group of processes) which holds an
  89 fcntl exclusive lock on the first byte of the plain file which has the
  90 specified name.  A holder of the lock (and only a holder of the lock)
  91 may delete the file or change the inode to which the name refers, and
  92 as soon as it does so it ceases to hold the lock.
  93 .PP
  94 Any process may create the file if it does not exist.  There is no
  95 need for the file to contain any actual data.  Indeed, actually using
  96 the file for data storage is strongly disrecommended, as this will
  97 foreclose most strategies for reliable update.  Use a separate
  98 lockfile instead.
  99 .PP
 100 Ability to obtain the lock corresponds to write permission on the file
 101 (and of course permission to create the  file, if it does not already
 102 exist).  However, processes with only read permission on the file can
 103 prevent the lock being acquired at all; therefore lockfiles should not
 104 usually be world-readable.
 105 .PP
 106 When a (group of) processes wishes to acquire the lock, it should open
 107 the file
 108 (with
 109 .BR O_CREAT )
 110 and lock it with
 111 .BR fcntl (2)
 112 .BR F_RWLCK ,
 113 operation
 114 .B F_SETLK
 115 or
 116 .BR F_SETLKW .
 117 If this succeeds it should fstat the file descriptor it has, and the
 118 file by its path.  If the device and inode match then the lock has
 119 been acquired and remains acquired until that group of processes
 120 changes which file the name refers to, deletes the file, or releases
 121 the fcntl lock.  If they do not then another process acquired the lock
 122 and deleted the file in the meantime; you must now close your
 123 filedescriptor and start again.
 124 .B with-lock-ex
 125 follows this specification.
 126 .PP
 127 Note that
 128 .BR flock (2)
 129 is a different kind of lock to
 130 .BR fcntl (2).
 131 .B with-lock-ex
 132 uses
 133 .BR fcntl .
 134 .SH AUTHOR
 135 This Manual page was written by Matthew Vernon <matthew@debian.org>
 136 and enhanced by Ian Jackson <ian@chiark.greenend.org.uk>, in 2003, but
 137 may be used by anyone.
 138 .SH COPYRIGHT
 139 with-lock-ex was written by Ian Jackons <ian@chiark.greenend.org.uk>
 140 in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public
 141 domain.
 142 .SH "SEE ALSO"
 143 .BR fcntl (2),
 144 .BR flock (2),
 145 .BR chmod (2)