From 07bcf3ad73b5d4555e58cf4c7a2e94fb66f4cfa5 Mon Sep 17 00:00:00 2001 From: ianmdlvl Date: Sun, 13 Jul 2003 22:39:43 +0000 Subject: [PATCH] much more detail --- cprogs/with-lock-ex.1 | 81 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 79 insertions(+), 2 deletions(-) diff --git a/cprogs/with-lock-ex.1 b/cprogs/with-lock-ex.1 index 6f89277..63ac832 100644 --- a/cprogs/with-lock-ex.1 +++ b/cprogs/with-lock-ex.1 @@ -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 but +This Manual page was written by Matthew Vernon +and enhanced by Ian Jackson , in 2003, but may be used by anyone. .SH COPYRIGHT with-lock-ex was written by Ian Jackons -- 2.30.2