X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=chiark-utils.git;a=blobdiff_plain;f=cprogs%2Fwith-lock-ex.1;h=941d1d9a0fa3a2d59d8c8aa2baa98ca0de7806ea;hp=6f8927735af3add6883b637037b8c19f09d5591c;hb=07abfd57eb09934ad42dd3b2b12c46ee237b4b89;hpb=92105cecb1af534119a7376d3cda100057f88032 diff --git a/cprogs/with-lock-ex.1 b/cprogs/with-lock-ex.1 index 6f89277..941d1d9 100644 --- a/cprogs/with-lock-ex.1 +++ b/cprogs/with-lock-ex.1 @@ -3,7 +3,7 @@ with-lock-ex \- file locker .SH SYNOPSIS .B with-lock-ex -.RB [\| \-w \||\| \-q \||\| \-f \|] +.BR \-w \||\| \-q \||\| \-f .I lockfile command .IR args \ \|.\|.\|. .br @@ -13,20 +13,135 @@ 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 umask has +.BR w . .SH OPTIONS .TP .B \-w -wait for the lock +Wait for the lock to be available. .TP .B \-f -fail if the lock cannot be acquired +Fail (printing a message to stderr and exiting 255) if the lock cannot +be acquired immediately because another process has it. .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 immediately because another +process has it. +.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. +.PP +Then, for any two locks +.I X +and +.I Y +with +.IR X > Y +it is forbidden to acquire +.I X +while holding +.IR Y . +Instead, acquire +.I X +first, or release +.I Y +before (re)acquiring +.I X +and +.I Y +in that order. +.PP +(There are more complicated ways of avoiding deadlocks, but a lock +hierarchy is simple to understand and implement. If it does not meet +your needs, consult the literature.) +.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. +.PP +Note that +.BR flock (2) +is a different kind of lock to +.BR fcntl (2). +.B with-lock-ex +uses +.BR fcntl . .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 +with-lock-ex was written by Ian Jackson in 1993, 1994, 1995, 1996, 1998, 1999. He has placed it in the public domain. +.SH "SEE ALSO" +.BR fcntl (2), +.BR flock (2), +.BR chmod (2)