chiark / gitweb /
much more detail
authorianmdlvl <ianmdlvl>
Sun, 13 Jul 2003 22:39:43 +0000 (22:39 +0000)
committerianmdlvl <ianmdlvl>
Sun, 13 Jul 2003 22:39:43 +0000 (22:39 +0000)
cprogs/with-lock-ex.1

index 6f89277..63ac832 100644 (file)
@@ -13,6 +13,11 @@ the remainder of its arguments to
 .BR exec (2);
 when that process terminates the fd will be closed and the file
 unlocked automatically by the kernel.
+.PP
+If the file does not exist it is created, with permissions
+.B rw
+for each user class for which the default umask has
+.BR w .
 .SH OPTIONS
 .TP
 .B \-w
@@ -22,9 +27,81 @@ wait for the lock
 fail if the lock cannot be acquired
 .TP
 .B \-q
-silently do nothing if the lock cannot be acquired
+silently do nothing (ie, exit 0 instead of executing the specified
+process) if the lock cannot be acquired
+.SH 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.
+.PP
+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
+.IP
+.B with-lock-ex -q
+.I lockfile
+.B rm
+.I lockfile
+.SH 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
+.I A
+and
+.I B
+which a process might lock simultaneously, either
+.IR A > B
+or
+.IR B > A
+where the relation > is transitive and noncyclic.
+.SH LOCKING PROTOCOL
+The locking protocol used by
+.B with-lock-ex
+is as follows:
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+When a (group of) processes wishes to acquire the lock, it should open
+the file
+(with
+.BR O_CREAT )
+and lock it with
+.BR fcntl (2)
+.BR F_RWLCK ,
+operation
+.B F_SETLK
+or
+.BR 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.
+.B with-lock-ex
+follows this specification.
 .SH AUTHOR
-This Manual page was written by Matthew Vernon <matthew@debian.org> but 
+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.
 .SH COPYRIGHT
 with-lock-ex was written by Ian Jackons <ian@chiark.greenend.org.uk>