| .\" ----------------------------------------------------------------------- |
| .\" |
| .\" 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 |
| \fB\-s\fP, \fB\-\-shared\fP |
| Obtain a shared lock, sometimes called a read lock. |
| .TP |
| \fB\-x\fP, \fB\-e\fP, \fB\-\-exclusive\fP |
| Obtain an exclusive lock, sometimes called a write lock. This is the |
| default. |
| .TP |
| \fB\-u\fP, \fB\-\-unlock\fP |
| 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 |
| \fB\-n\fP, \fB\-\-nb\fP, \fB\-\-nonblock\fP |
| Fail rather than wait if the lock cannot be |
| immediately acquired. |
| See the |
| .B \-E |
| option for the exit code used. |
| .TP |
| \fB\-w\fP, \fB\-\-wait\fP, \fB\-\-timeout\fP \fIseconds\fP |
| 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. |
| .TP |
| \fB\-o\fP, \fB\-\-close\fP |
| 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 |
| \fB\-E\fP, \fB\-\-conflict\-exit\-code\fP \fInumber\fP |
| 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 1. |
| .TP |
| \fB\-c\fP, \fB\-\-command\fP \fIcommand\fP |
| Pass a single |
| .IR command , |
| without arguments, to the shell with |
| .BR -c . |
| .TP |
| \fB\-h\fP, \fB\-\-help\fP |
| Display help text and exit. |
| .IP "\fB\-V, \-\-version\fP" |
| Display version information 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 ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
| Linux Kernel Archive |
| .UE . |