mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-08 20:26:31 +00:00
09a7fe0a55
This is most useful inside a shell script, allowing one to lock just portions of a script rather than having to wrap the entire script in a lock. PR: 262738 Reviewed by: 0mp, allanjude (both previous versions) Co-authored-by: Daniel O'Connor <darius@dons.net.au> Sponsored by: Klara, Inc. Differential Revision: https://reviews.freebsd.org/D42718
261 lines
6.4 KiB
Groff
261 lines
6.4 KiB
Groff
.\"
|
|
.\" 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
|