]>
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 | .\" ----------------------------------------------------------------------- | |
e9da7722 | 27 | .TH FLOCK 1 "September 2011" "util-linux" "User Commands" |
d162fcb5 | 28 | .SH NAME |
232dc924 | 29 | flock \- manage locks from shell scripts |
d162fcb5 | 30 | .SH SYNOPSIS |
e9da7722 SK |
31 | .B flock |
32 | [options] <file> -c <command> | |
33 | .br | |
34 | .B flock | |
35 | [options] <directory> -c <command> | |
36 | .br | |
37 | .B flock | |
38 | [options] <file descriptor number> | |
d162fcb5 | 39 | .SH DESCRIPTION |
d162fcb5 | 40 | .PP |
baf39af1 KZ |
41 | This utility manages |
42 | .BR flock (2) | |
43 | locks from within shell scripts or the command line. | |
d162fcb5 | 44 | .PP |
387bae93 | 45 | The first and second forms wrap the lock around the executing a command, in |
e9da7722 | 46 | a manner similar to |
baf39af1 KZ |
47 | .BR su (1) |
48 | or | |
49 | .BR newgrp (1). | |
e9da7722 SK |
50 | It locks a specified file or directory, which is created (assuming |
51 | appropriate permissions), if it does not already exist. By default, if the | |
52 | lock cannot be immediately acquired, | |
53 | .B flock | |
baf39af1 | 54 | waits until the lock is available. |
e9da7722 SK |
55 | .PP |
56 | The third form uses open file by file descriptor number. See examples how | |
1f338fe1 | 57 | that can be used. |
baf39af1 KZ |
58 | .SH OPTIONS |
59 | .TP | |
60 | \fB\-s\fP, \fB\-\-shared\fP | |
61 | Obtain a shared lock, sometimes called a read lock. | |
62 | .TP | |
a120aaa7 | 63 | \fB\-x\fP, \fB\-e\fP, \fB\-\-exclusive\fP |
baf39af1 KZ |
64 | Obtain an exclusive lock, sometimes called a write lock. This is the |
65 | default. | |
66 | .TP | |
67 | \fB\-u\fP, \fB\-\-unlock\fP | |
e9da7722 SK |
68 | Drop a lock. This is usually not required, since a lock is automatically |
69 | dropped when the file is closed. However, it may be required in special | |
70 | cases, for example if the enclosed command group may have forked a background | |
71 | process which should not be holding the lock. | |
baf39af1 | 72 | .TP |
a120aaa7 | 73 | \fB\-n\fP, \fB\-\-nb\fP, \fB\-\-nonblock\fP |
baf39af1 KZ |
74 | Fail (with an exit code of 1) rather than wait if the lock cannot be |
75 | immediately acquired. | |
76 | .TP | |
a120aaa7 | 77 | \fB\-w\fP, \fB\-\-wait\fP, \fB\-\-timeout\fP \fIseconds\fP |
baf39af1 | 78 | Fail (with an exit code of 1) if the lock cannot be acquired within |
e9da7722 SK |
79 | .IR seconds . |
80 | Decimal fractional values are allowed. | |
baf39af1 KZ |
81 | .TP |
82 | \fB\-o\fP, \fB\-\-close\fP | |
83 | Close the file descriptor on which the lock is held before executing | |
e9da7722 SK |
84 | .BR command\ . |
85 | This is useful if | |
86 | .B command | |
87 | spawns a child process which should not be holding the lock. | |
baf39af1 | 88 | .TP |
a120aaa7 | 89 | \fB\-c\fP, \fB\-\-command\fP \fIcommand\fP |
e9da7722 SK |
90 | Pass a single |
91 | .IR command , | |
92 | without arguments, to the shell with | |
93 | .BR -c . | |
a120aaa7 | 94 | .TP |
baf39af1 KZ |
95 | \fB\-h\fP, \fB\-\-help\fP |
96 | Print a help message. | |
e9da7722 SK |
97 | .IP "\fB\-V, \-\-version\fP" |
98 | Show version number and exit. | |
99 | .SH EXAMPLES | |
100 | .TP | |
101 | shell1> flock /tmp -c cat | |
102 | .TQ | |
103 | shell2> flock -w .007 /tmp -c echo; /bin/echo $? | |
104 | Set exclusive lock to directory /tmp and the second command will fail. | |
105 | .TP | |
106 | shell1> flock -s /tmp -c cat | |
107 | .TQ | |
108 | shell2> flock -s -w .007 /tmp -c echo; /bin/echo $? | |
109 | Set shared lock to directory /tmp and the second command will not fail. | |
110 | Notice that attempting to get exclusive lock with second command would fail. | |
111 | .TP | |
112 | ( | |
113 | .TQ | |
114 | flock -n 9 || exit 1 | |
115 | .TQ | |
116 | # ... commands executed under lock ... | |
117 | .TQ | |
118 | ) 9>/var/lock/mylockfile | |
119 | The form is convenient inside shell scripts. The mode used to open the file | |
120 | doesn't matter to | |
121 | .BR flock ; | |
122 | using | |
123 | .I > | |
124 | or | |
125 | .I >> | |
126 | allows the lockfile to be created if it does not already exist, however, | |
127 | write permission is required. Using | |
128 | .I < | |
129 | requires that the file already exists but only read permission is required. | |
130 | .SH "EXIT STATUS" | |
131 | The command uses | |
132 | .B sysexits.h | |
133 | return values for everything else but an options | |
134 | .I \-n | |
135 | or | |
136 | .I \-w | |
137 | failures which return 1. | |
d162fcb5 | 138 | .SH AUTHOR |
e9da7722 SK |
139 | .UR hpa@zytor.com |
140 | H. Peter Anvin | |
141 | .UE | |
baf39af1 | 142 | .SH COPYRIGHT |
a120aaa7 | 143 | Copyright \(co 2003\-2006 H. Peter Anvin. |
baf39af1 KZ |
144 | .br |
145 | This is free software; see the source for copying conditions. There is NO | |
146 | warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
147 | .SH "SEE ALSO" | |
148 | .BR flock (2) | |
86d62711 | 149 | .SH AVAILABILITY |
601d12fb | 150 | The flock command is part of the util-linux package and is available from |
e9da7722 SK |
151 | .UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
152 | Linux Kernel Archive | |
153 | .UE . |