| .\" ----------------------------------------------------------------------- |
| .\" |
| .\" 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 . |