]>
Commit | Line | Data |
---|---|---|
baf39af1 | 1 | .\" ----------------------------------------------------------------------- |
e9da7722 | 2 | .\" |
a120aaa7 | 3 | .\" Copyright 2003-2006 H. Peter Anvin - All Rights Reserved |
baf39af1 KZ |
4 | .\" |
5 | .\" Permission is hereby granted, free of charge, to any person | |
6 | .\" obtaining a copy of this software and associated documentation | |
7 | .\" files (the "Software"), to deal in the Software without | |
8 | .\" restriction, including without limitation the rights to use, | |
9 | .\" copy, modify, merge, publish, distribute, sublicense, and/or | |
10 | .\" sell copies of the Software, and to permit persons to whom | |
11 | .\" the Software is furnished to do so, subject to the following | |
12 | .\" conditions: | |
e9da7722 | 13 | .\" |
baf39af1 KZ |
14 | .\" The above copyright notice and this permission notice shall |
15 | .\" be included in all copies or substantial portions of the Software. | |
e9da7722 | 16 | .\" |
baf39af1 KZ |
17 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
18 | .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES | |
19 | .\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND | |
20 | .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT | |
21 | .\" HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, | |
22 | .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING | |
23 | .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR | |
24 | .\" OTHER DEALINGS IN THE SOFTWARE. | |
25 | .\" | |
26 | .\" ----------------------------------------------------------------------- | |
e33ee284 | 27 | .TH FLOCK 1 "July 2014" "util-linux" "User Commands" |
d162fcb5 | 28 | .SH NAME |
232dc924 | 29 | flock \- manage locks from shell scripts |
d162fcb5 | 30 | .SH SYNOPSIS |
e9da7722 | 31 | .B flock |
e33ee284 BS |
32 | [options] |
33 | .IR file | "directory command " [ arguments ] | |
e9da7722 SK |
34 | .br |
35 | .B flock | |
e33ee284 BS |
36 | [options] |
37 | .IR file | directory | |
38 | .BI \-c " command" | |
e9da7722 SK |
39 | .br |
40 | .B flock | |
e33ee284 | 41 | .RI [options] " number" |
d162fcb5 | 42 | .SH DESCRIPTION |
baf39af1 KZ |
43 | This utility manages |
44 | .BR flock (2) | |
e33ee284 | 45 | locks from within shell scripts or from the command line. |
d162fcb5 | 46 | .PP |
e33ee284 BS |
47 | The first and second of the above forms wrap the lock around the execution of a |
48 | .IR command , | |
49 | in a manner similar to | |
baf39af1 KZ |
50 | .BR su (1) |
51 | or | |
52 | .BR newgrp (1). | |
e33ee284 BS |
53 | They lock a specified \fIfile\fR or \fIdirectory\fR, which is created (assuming |
54 | appropriate permissions) if it does not already exist. By default, if the | |
e9da7722 SK |
55 | lock cannot be immediately acquired, |
56 | .B flock | |
baf39af1 | 57 | waits until the lock is available. |
e9da7722 | 58 | .PP |
e33ee284 BS |
59 | The third form uses an open file by its file descriptor \fInumber\fR. |
60 | See the examples below for how that can be used. | |
baf39af1 KZ |
61 | .SH OPTIONS |
62 | .TP | |
5e43af7e BS |
63 | .BR \-c , " \-\-command " \fIcommand |
64 | Pass a single \fIcommand\fR, without arguments, to the shell with | |
65 | .BR \-c . | |
baf39af1 | 66 | .TP |
b06c1ca6 | 67 | .BR \-E , " \-\-conflict\-exit\-code " \fInumber |
a87f49f6 | 68 | The exit status used when the \fB\-n\fP option is in use, and the |
5e43af7e BS |
69 | conflicting lock exists, or the \fB\-w\fP option is in use, |
70 | and the timeout is reached. The default value is \fB1\fR. | |
e5781b3d | 71 | The \fInumber\fR has to be in the range of 0 to 255. |
5e43af7e | 72 | .TP |
70325140 TB |
73 | .BR \-F , " \-\-no\-fork" |
74 | Do not fork before executing | |
75 | .IR command . | |
76 | Upon execution the flock process is replaced by | |
0bb7e904 | 77 | .I command |
70325140 TB |
78 | which continues to hold the lock. This option is incompatible with |
79 | \fB\-\-close\fR as there would otherwise be nothing left to hold the lock. | |
80 | .TP | |
5e43af7e | 81 | .BR \-e , " \-x" , " \-\-exclusive" |
baf39af1 KZ |
82 | Obtain an exclusive lock, sometimes called a write lock. This is the |
83 | default. | |
84 | .TP | |
5e43af7e | 85 | .BR \-n , " \-\-nb" , " \-\-nonblock" |
827b1cee | 86 | Fail rather than wait if the lock cannot be |
baf39af1 | 87 | immediately acquired. |
827b1cee | 88 | See the |
e33ee284 | 89 | .B \-E |
a87f49f6 | 90 | option for the exit status used. |
baf39af1 | 91 | .TP |
5e43af7e | 92 | .BR \-o , " \-\-close" |
baf39af1 | 93 | Close the file descriptor on which the lock is held before executing |
e33ee284 | 94 | .IR command . |
e9da7722 | 95 | This is useful if |
e33ee284 | 96 | .I command |
e9da7722 | 97 | spawns a child process which should not be holding the lock. |
baf39af1 | 98 | .TP |
5e43af7e BS |
99 | .BR \-s , " \-\-shared" |
100 | Obtain a shared lock, sometimes called a read lock. | |
827b1cee | 101 | .TP |
5e43af7e BS |
102 | .BR \-u , " \-\-unlock" |
103 | Drop a lock. This is usually not required, since a lock is automatically | |
104 | dropped when the file is closed. However, it may be required in special | |
105 | cases, for example if the enclosed command group may have forked a background | |
106 | process which should not be holding the lock. | |
a120aaa7 | 107 | .TP |
5e43af7e BS |
108 | .BR \-w , " \-\-wait" , " \-\-timeout " \fIseconds |
109 | Fail if the lock cannot be acquired within | |
110 | .IR seconds . | |
111 | Decimal fractional values are allowed. | |
112 | See the | |
113 | .B \-E | |
a87f49f6 | 114 | option for the exit status used. The zero number of |
0bb7e904 | 115 | .I seconds |
c4604c38 | 116 | is interpreted as \fB\-\-nonblock\fR. |
5e43af7e | 117 | .TP |
59dc9f28 SK |
118 | .B \-\-verbose |
119 | Report how long it took to acquire the lock, or why the lock could not be | |
120 | obtained. | |
121 | .TP | |
5e43af7e | 122 | .BR \-V , " \-\-version" |
b4362b6f | 123 | Display version information and exit. |
5e43af7e BS |
124 | .TP |
125 | .BR \-h , " \-\-help" | |
126 | Display help text and exit. | |
67e63c12 MK |
127 | .SH EXIT STATUS |
128 | The command uses | |
129 | .B sysexits.h | |
130 | exit status values for everything, except when using either of the options | |
131 | .B \-n | |
132 | or | |
133 | .B \-w | |
3c560686 | 134 | which report a failure to acquire the lock with an exit status given by the |
67e63c12 | 135 | .B \-E |
e5781b3d KZ |
136 | option, or 1 by default. The exit status given by |
137 | .B \-E has to be in the range of 0 to 255. | |
67e63c12 MK |
138 | .PP |
139 | When using the \fIcommand\fR variant, and executing the child worked, then | |
140 | the exit status is that of the child command. | |
3bc92f31 | 141 | .SH EXAMPLES |
5db212c0 | 142 | Note that "shell> " in examples is a command line prompt. |
e9da7722 | 143 | .TP |
1c4c6024 | 144 | shell1> flock /tmp \-c cat |
e9da7722 | 145 | .TQ |
1c4c6024 | 146 | shell2> flock \-w .007 /tmp \-c echo; /bin/echo $? |
e9da7722 SK |
147 | Set exclusive lock to directory /tmp and the second command will fail. |
148 | .TP | |
1c4c6024 | 149 | shell1> flock \-s /tmp \-c cat |
e9da7722 | 150 | .TQ |
1c4c6024 | 151 | shell2> flock \-s \-w .007 /tmp \-c echo; /bin/echo $? |
e9da7722 SK |
152 | Set shared lock to directory /tmp and the second command will not fail. |
153 | Notice that attempting to get exclusive lock with second command would fail. | |
154 | .TP | |
1c4c6024 | 155 | shell> flock \-x local-lock-file echo 'a b c' |
295dd902 MF |
156 | Grab the exclusive lock "local-lock-file" before running echo with 'a b c'. |
157 | .TP | |
e9da7722 SK |
158 | ( |
159 | .TQ | |
1c4c6024 | 160 | flock \-n 9 || exit 1 |
e9da7722 SK |
161 | .TQ |
162 | # ... commands executed under lock ... | |
163 | .TQ | |
164 | ) 9>/var/lock/mylockfile | |
165 | The form is convenient inside shell scripts. The mode used to open the file | |
166 | doesn't matter to | |
167 | .BR flock ; | |
168 | using | |
169 | .I > | |
170 | or | |
171 | .I >> | |
172 | allows the lockfile to be created if it does not already exist, however, | |
173 | write permission is required. Using | |
174 | .I < | |
175 | requires that the file already exists but only read permission is required. | |
295dd902 | 176 | .TP |
1c4c6024 | 177 | [ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock \-en "$0" "$0" "$@" || : |
295dd902 MF |
178 | This is useful boilerplate code for shell scripts. Put it at the top of the |
179 | shell script you want to lock and it'll automatically lock itself on the first | |
180 | run. If the env var $FLOCKER is not set to the shell script that is being run, | |
181 | then execute flock and grab an exclusive non-blocking lock (using the script | |
182 | itself as the lock file) before re-execing itself with the right arguments. It | |
183 | also sets the FLOCKER env var to the right value so it doesn't run again. | |
966bcac3 | 184 | .TP |
5db212c0 | 185 | shell> exec 4<>/var/lock/mylockfile |
966bcac3 | 186 | .TQ |
5db212c0 | 187 | shell> flock -n 4 |
966bcac3 J |
188 | This form is convenient for locking a file without spawning a subprocess. |
189 | The shell opens the lock file for reading and writing as file descriptor 4, | |
190 | then flock is used to lock the descriptor. | |
a8d0d330 | 191 | .SH AUTHORS |
e9da7722 SK |
192 | .UR hpa@zytor.com |
193 | H. Peter Anvin | |
194 | .UE | |
baf39af1 | 195 | .SH COPYRIGHT |
a120aaa7 | 196 | Copyright \(co 2003\-2006 H. Peter Anvin. |
baf39af1 KZ |
197 | .br |
198 | This is free software; see the source for copying conditions. There is NO | |
199 | warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
5a829806 | 200 | .SH SEE ALSO |
baf39af1 | 201 | .BR flock (2) |
86d62711 | 202 | .SH AVAILABILITY |
601d12fb | 203 | The flock command is part of the util-linux package and is available from |
d673b74e | 204 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
e9da7722 SK |
205 | Linux Kernel Archive |
206 | .UE . |