diff options
Diffstat (limited to 'usr.bin/lockf/lockf.1')
| -rw-r--r-- | usr.bin/lockf/lockf.1 | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/usr.bin/lockf/lockf.1 b/usr.bin/lockf/lockf.1 new file mode 100644 index 000000000000..d73033101632 --- /dev/null +++ b/usr.bin/lockf/lockf.1 @@ -0,0 +1,260 @@ +.\" +.\" Copyright (C) 1998 John D. Polstra. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN D. POLSTRA AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL JOHN D. POLSTRA OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 25, 2023 +.Dt LOCKF 1 +.Os +.Sh NAME +.Nm lockf +.Nd execute a command while holding a file lock +.Sh SYNOPSIS +.Nm +.Op Fl knsw +.Op Fl t Ar seconds +.Ar file +.Ar command +.Op Ar arguments +.Nm +.Op Fl s +.Op Fl t Ar seconds +.Ar fd +.Sh DESCRIPTION +The +.Nm +utility acquires an exclusive lock on a +.Ar file , +creating it if necessary, +.Bf Em +and removing the file on exit unless explicitly told not to. +.Ef +While holding the lock, it executes a +.Ar command +with optional +.Ar arguments . +After the +.Ar command +completes, +.Nm +releases the lock, and removes the +.Ar file +unless the +.Fl k +option is specified. +.Bx Ns -style +locking is used, as described in +.Xr flock 2 ; +the mere existence of the +.Ar file +is not considered to constitute a lock. +.Pp +.Nm +may also be used to operate on a file descriptor instead of a file. +If no +.Ar command +is supplied, then +.Ar fd +must be a file descriptor. +The version with a +.Ar command +may also be used with a file descriptor by supplying it as a path +.Pa /dev/fd/N , +where N is the desired file descriptor. +The +.Fl k +option is implied when a file descriptor is in use, and the +.Fl n +and +.Fl w +options are silently ignored. +This can be used to lock inside a shell script. +.Pp +If the +.Nm +utility is being used to facilitate concurrency between a number +of processes, it is recommended that the +.Fl k +option be used. +This will guarantee lock ordering, as well as implement +a performance enhanced algorithm which minimizes CPU load associated +with concurrent unlink, drop and re-acquire activity. +It should be noted +that if the +.Fl k +option is not used, then no guarantees around lock ordering can be made. +.Pp +The following options are supported: +.Bl -tag -width ".Fl t Ar seconds" +.It Fl k +Causes the lock file to be kept (not removed) after the command +completes. +.It Fl s +Causes +.Nm +to operate silently. +Failure to acquire the lock is indicated only in the exit status. +.It Fl n +Causes +.Nm +to fail if the specified lock +.Ar file +does not exist. +If +.Fl n +is not specified, +.Nm +will create +.Ar file +if necessary. +.It Fl t Ar seconds +Specifies a timeout for waiting for the lock. +By default, +.Nm +waits indefinitely to acquire the lock. +If a timeout is specified with this option, +.Nm +will wait at most the given number of +.Ar seconds +before giving up. +A timeout of 0 may be given, in which case +.Nm +will fail unless it can acquire the lock immediately. +When a lock times out, +.Ar command +is +.Em not +executed. +.It Fl w +Causes +.Nm +to open +.Ar file +for writing rather than reading. +This is necessary on filesystems (including NFSv4) where a file which +has been opened read-only cannot be exclusively locked. +.El +.Pp +In no event will +.Nm +break a lock that is held by another process. +.Sh EXIT STATUS +If +.Nm +successfully acquires the lock, it returns the exit status produced by +.Ar command . +Otherwise, it returns one of the exit codes defined in +.Xr sysexits 3 , +as follows: +.Bl -tag -width ".Dv EX_CANTCREAT" +.It Dv EX_TEMPFAIL +The specified lock file was already locked by another process. +.It Dv EX_CANTCREAT +The +.Nm +utility +was unable to create the lock file, e.g., because of insufficient access +privileges. +.It Dv EX_UNAVAILABLE +The +.Fl n +option is specified and the specified lock file does not exist. +.It Dv EX_USAGE +There was an error on the +.Nm +command line. +.It Dv EX_OSERR +A system call (e.g., +.Xr fork 2 ) +failed unexpectedly. +.It Dv EX_SOFTWARE +The +.Ar command +did not exit normally, +but may have been signaled or stopped. +.El +.Sh EXAMPLES +The first job takes a lock and sleeps for 5 seconds in the background. +The second job tries to get the lock and timeouts after 1 second (PID numbers +will differ): +.Bd -literal -offset indent +$ lockf mylock sleep 5 & lockf -t 1 mylock echo "Success" +[1] 94410 +lockf: mylock: already locked +.Ed +.Pp +The first job takes a lock and sleeps for 1 second in the background. +The second job waits up to 5 seconds to take the lock and echoes the message on +success (PID numbers will differ): +.Bd -literal -offset indent +$ lockf mylock sleep 1 & lockf -t 5 mylock echo "Success" +[1] 19995 +Success +[1]+ Done lockf mylock sleep 1 +.Ed +Lock a file and run a script, return immediately if the lock is not +available. Do not delete the file afterward so lock order is +guaranteed. +.Pp +.Dl $ lockf -t 0 -k /tmp/my.lock myscript +.Pp +Protect a section of a shell script with a lock, wait up to 5 seconds +for it to become available. +Note that the shell script has opened the lock file +.Fa /tmp/my.lock , +and +.Nm +is performing the lock call exclusively via the passed in file descriptor (9). +In this case +.Fl k +is implied, and +.Fl w +has no effect because the file has already been opened by the shell. +This example assumes that +.Ql > +is implemented in the shell by opening and truncating +.Pa /tmp/my.lock , +rather than by replacing the lock file. +.Bd -literal -offset indent +( + lockf -s -t 5 9 + if [ $? -ne 0 ]; then + echo "Failed to obtain lock" + exit 1 + fi + + echo Start + # Do some stuff + echo End +) 9>/tmp/my.lock +.Ed +.Sh SEE ALSO +.Xr flock 2 , +.Xr lockf 3 , +.Xr sysexits 3 +.Sh HISTORY +A +.Nm +utility first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An John Polstra Aq Mt jdp@polstra.com |