198 lines
6.4 KiB
Groff
198 lines
6.4 KiB
Groff
.\" -----------------------------------------------------------------------
|
|
.\"
|
|
.\" Copyright 2003-2006 H. Peter Anvin - All Rights Reserved
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person
|
|
.\" obtaining a copy of this software and associated documentation
|
|
.\" files (the "Software"), to deal in the Software without
|
|
.\" restriction, including without limitation the rights to use,
|
|
.\" copy, modify, merge, publish, distribute, sublicense, and/or
|
|
.\" sell copies of the Software, and to permit persons to whom
|
|
.\" the Software is furnished to do so, subject to the following
|
|
.\" conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall
|
|
.\" be included in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
|
|
.\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
|
.\" HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
|
.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" -----------------------------------------------------------------------
|
|
.TH FLOCK 1 "July 2014" "util-linux" "User Commands"
|
|
.SH NAME
|
|
flock \- manage locks from shell scripts
|
|
.SH SYNOPSIS
|
|
.B flock
|
|
[options]
|
|
.IR file | "directory command " [ arguments ]
|
|
.br
|
|
.B flock
|
|
[options]
|
|
.IR file | directory
|
|
.BI \-c " command"
|
|
.br
|
|
.B flock
|
|
.RI [options] " number"
|
|
.SH DESCRIPTION
|
|
.PP
|
|
This utility manages
|
|
.BR flock (2)
|
|
locks from within shell scripts or from the command line.
|
|
.PP
|
|
The first and second of the above forms wrap the lock around the execution of a
|
|
.IR command ,
|
|
in a manner similar to
|
|
.BR su (1)
|
|
or
|
|
.BR newgrp (1).
|
|
They lock a specified \fIfile\fR or \fIdirectory\fR, which is created (assuming
|
|
appropriate permissions) if it does not already exist. By default, if the
|
|
lock cannot be immediately acquired,
|
|
.B flock
|
|
waits until the lock is available.
|
|
.PP
|
|
The third form uses an open file by its file descriptor \fInumber\fR.
|
|
See the examples below for how that can be used.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-c , " \-\-command " \fIcommand
|
|
Pass a single \fIcommand\fR, without arguments, to the shell with
|
|
.BR \-c .
|
|
.TP
|
|
.BR \-E , " \-\-conflict\-exit\-code " \fInumber
|
|
The exit code used when the \fB\-n\fP option is in use, and the
|
|
conflicting lock exists, or the \fB\-w\fP option is in use,
|
|
and the timeout is reached. The default value is \fB1\fR.
|
|
.TP
|
|
.BR \-F , " \-\-no\-fork"
|
|
Do not fork before executing
|
|
.IR command .
|
|
Upon execution the flock process is replaced by
|
|
.I command
|
|
which continues to hold the lock. This option is incompatible with
|
|
\fB\-\-close\fR as there would otherwise be nothing left to hold the lock.
|
|
.TP
|
|
.BR \-e , " \-x" , " \-\-exclusive"
|
|
Obtain an exclusive lock, sometimes called a write lock. This is the
|
|
default.
|
|
.TP
|
|
.BR \-n , " \-\-nb" , " \-\-nonblock"
|
|
Fail rather than wait if the lock cannot be
|
|
immediately acquired.
|
|
See the
|
|
.B \-E
|
|
option for the exit code used.
|
|
.TP
|
|
.BR \-o , " \-\-close"
|
|
Close the file descriptor on which the lock is held before executing
|
|
.IR command .
|
|
This is useful if
|
|
.I command
|
|
spawns a child process which should not be holding the lock.
|
|
.TP
|
|
.BR \-s , " \-\-shared"
|
|
Obtain a shared lock, sometimes called a read lock.
|
|
.TP
|
|
.BR \-u , " \-\-unlock"
|
|
Drop a lock. This is usually not required, since a lock is automatically
|
|
dropped when the file is closed. However, it may be required in special
|
|
cases, for example if the enclosed command group may have forked a background
|
|
process which should not be holding the lock.
|
|
.TP
|
|
.BR \-w , " \-\-wait" , " \-\-timeout " \fIseconds
|
|
Fail if the lock cannot be acquired within
|
|
.IR seconds .
|
|
Decimal fractional values are allowed.
|
|
See the
|
|
.B \-E
|
|
option for the exit code used. The zero number of
|
|
.I seconds
|
|
is interpreted as \fB\-\-nonblock\fR.
|
|
.TP
|
|
.B \-\-verbose
|
|
Report how long it took to acquire the lock, or why the lock could not be
|
|
obtained.
|
|
.TP
|
|
.BR \-V , " \-\-version"
|
|
Display version information and exit.
|
|
.TP
|
|
.BR \-h , " \-\-help"
|
|
Display help text and exit.
|
|
.SH EXAMPLES
|
|
.TP
|
|
shell1> flock /tmp -c cat
|
|
.TQ
|
|
shell2> flock -w .007 /tmp -c echo; /bin/echo $?
|
|
Set exclusive lock to directory /tmp and the second command will fail.
|
|
.TP
|
|
shell1> flock -s /tmp -c cat
|
|
.TQ
|
|
shell2> flock -s -w .007 /tmp -c echo; /bin/echo $?
|
|
Set shared lock to directory /tmp and the second command will not fail.
|
|
Notice that attempting to get exclusive lock with second command would fail.
|
|
.TP
|
|
shell> flock -x local-lock-file echo 'a b c'
|
|
Grab the exclusive lock "local-lock-file" before running echo with 'a b c'.
|
|
.TP
|
|
(
|
|
.TQ
|
|
flock -n 9 || exit 1
|
|
.TQ
|
|
# ... commands executed under lock ...
|
|
.TQ
|
|
) 9>/var/lock/mylockfile
|
|
The form is convenient inside shell scripts. The mode used to open the file
|
|
doesn't matter to
|
|
.BR flock ;
|
|
using
|
|
.I >
|
|
or
|
|
.I >>
|
|
allows the lockfile to be created if it does not already exist, however,
|
|
write permission is required. Using
|
|
.I <
|
|
requires that the file already exists but only read permission is required.
|
|
.TP
|
|
[ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock -en "$0" "$0" "$@" || :
|
|
This is useful boilerplate code for shell scripts. Put it at the top of the
|
|
shell script you want to lock and it'll automatically lock itself on the first
|
|
run. If the env var $FLOCKER is not set to the shell script that is being run,
|
|
then execute flock and grab an exclusive non-blocking lock (using the script
|
|
itself as the lock file) before re-execing itself with the right arguments. It
|
|
also sets the FLOCKER env var to the right value so it doesn't run again.
|
|
.SH "EXIT STATUS"
|
|
The command uses
|
|
.B sysexits.h
|
|
return values for everything, except when using either of the options
|
|
.B \-n
|
|
or
|
|
.B \-w
|
|
which report a failure to acquire the lock with a return value given by the
|
|
.B \-E
|
|
option, or 1 by default.
|
|
.PP
|
|
When using the \fIcommand\fR variant, and executing the child worked, then
|
|
the exit status is that of the child command.
|
|
.SH AUTHOR
|
|
.UR hpa@zytor.com
|
|
H. Peter Anvin
|
|
.UE
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2003\-2006 H. Peter Anvin.
|
|
.br
|
|
This is free software; see the source for copying conditions. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
.SH "SEE ALSO"
|
|
.BR flock (2)
|
|
.SH AVAILABILITY
|
|
The flock command is part of the util-linux package and is available from
|
|
.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
|
|
Linux Kernel Archive
|
|
.UE .
|