diff options
Diffstat (limited to '')
| -rw-r--r-- | sys-utils/flock.1 | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/sys-utils/flock.1 b/sys-utils/flock.1 new file mode 100644 index 0000000..5235f83 --- /dev/null +++ b/sys-utils/flock.1 @@ -0,0 +1,206 @@ +.\" ----------------------------------------------------------------------- +.\" +.\" 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 +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 status 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. +The \fInumber\fR has to be in the range of 0 to 255. +.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 status 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 status 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 EXIT STATUS +The command uses +.B sysexits.h +exit status 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 exit status given by the +.B \-E +option, or 1 by default. The exit status given by +.B \-E has to be in the range of 0 to 255. +.PP +When using the \fIcommand\fR variant, and executing the child worked, then +the exit status is that of the child command. +.SH EXAMPLES +Note that "shell> " in examples is a command line prompt. +.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. +.TP +shell> exec 4<>/var/lock/mylockfile +.TQ +shell> flock -n 4 +This form is convenient for locking a file without spawning a subprocess. +The shell opens the lock file for reading and writing as file descriptor 4, +then flock is used to lock the descriptor. +.SH AUTHORS +.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 . |