]>
Commit | Line | Data |
---|---|---|
baf39af1 KZ |
1 | .\" ----------------------------------------------------------------------- |
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: | |
13 | .\" | |
14 | .\" The above copyright notice and this permission notice shall | |
15 | .\" be included in all copies or substantial portions of the Software. | |
16 | .\" | |
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 | .\" ----------------------------------------------------------------------- | |
a120aaa7 | 27 | .TH FLOCK "1" "4 Feb 2006" "flock utility" "H. Peter Anvin" |
d162fcb5 | 28 | .SH NAME |
baf39af1 | 29 | flock \- Manage locks from shell scripts |
d162fcb5 | 30 | .SH SYNOPSIS |
baf39af1 KZ |
31 | \fBflock\fP [\fB\-sxon\fP] [\fB\-w\fP \fItimeout\fP] \fIlockfile\fP [\fB\-c\fP] \fIcommand...\fP |
32 | .PP | |
ff571739 AG |
33 | \fBflock\fP [\fB\-sxon\fP] [\fB\-w\fP \fItimeout\fP] \fIlockdir\fP [\fB\-c\fP] \fIcommand...\fP |
34 | .PP | |
baf39af1 | 35 | \fBflock\fP [\fB\-sxun\fP] [\fB\-w\fP \fItimeout\fP] \fIfd\fP |
d162fcb5 | 36 | .SH DESCRIPTION |
d162fcb5 | 37 | .PP |
baf39af1 KZ |
38 | This utility manages |
39 | .BR flock (2) | |
40 | locks from within shell scripts or the command line. | |
d162fcb5 | 41 | .PP |
ff571739 | 42 | The first and second forms wraps the lock around the executing a command, in a manner similar to |
baf39af1 KZ |
43 | .BR su (1) |
44 | or | |
45 | .BR newgrp (1). | |
ff571739 | 46 | It locks a specified file or directory, which is created (assuming appropriate |
baf39af1 | 47 | permissions), if it does not already exist. |
d162fcb5 | 48 | .PP |
ff571739 | 49 | The third form is convenient inside shell scripts, and is usually |
baf39af1 | 50 | used the following manner: |
d162fcb5 | 51 | .PP |
baf39af1 KZ |
52 | \fC( |
53 | .br | |
c348d934 | 54 | flock -n 9 |
baf39af1 KZ |
55 | .br |
56 | # ... commands executed under lock ... | |
57 | .br | |
2c26d56f | 58 | ) 9>/var/lock/mylockfile\fP |
d162fcb5 | 59 | .PP |
baf39af1 KZ |
60 | The mode used to open the file doesn't matter to \fBflock\fP; using |
61 | \fC>\fP or \fP>>\fP allows the lockfile to be created if it does not | |
62 | already exist, however, write permission is required; using \fC<\fP | |
63 | requires that the file already exists but only read permission is | |
64 | required. | |
d162fcb5 | 65 | .PP |
baf39af1 KZ |
66 | By default, if the lock cannot be immediately acquired, \fBflock\fP |
67 | waits until the lock is available. | |
68 | .SH OPTIONS | |
69 | .TP | |
70 | \fB\-s\fP, \fB\-\-shared\fP | |
71 | Obtain a shared lock, sometimes called a read lock. | |
72 | .TP | |
a120aaa7 | 73 | \fB\-x\fP, \fB\-e\fP, \fB\-\-exclusive\fP |
baf39af1 KZ |
74 | Obtain an exclusive lock, sometimes called a write lock. This is the |
75 | default. | |
76 | .TP | |
77 | \fB\-u\fP, \fB\-\-unlock\fP | |
78 | Drop a lock. This is usually not required, since a lock is | |
79 | automatically dropped when the file is closed. However, it may be | |
80 | required in special cases, for example if the enclosed command group | |
81 | may have forked a background process which should not be holding the | |
82 | lock. | |
83 | .TP | |
a120aaa7 | 84 | \fB\-n\fP, \fB\-\-nb\fP, \fB\-\-nonblock\fP |
baf39af1 KZ |
85 | Fail (with an exit code of 1) rather than wait if the lock cannot be |
86 | immediately acquired. | |
87 | .TP | |
a120aaa7 | 88 | \fB\-w\fP, \fB\-\-wait\fP, \fB\-\-timeout\fP \fIseconds\fP |
baf39af1 KZ |
89 | Fail (with an exit code of 1) if the lock cannot be acquired within |
90 | \fIseconds\fP seconds. Decimal fractional values are allowed. | |
91 | .TP | |
92 | \fB\-o\fP, \fB\-\-close\fP | |
93 | Close the file descriptor on which the lock is held before executing | |
94 | \fIcommand\fP. This is useful if \fIcommand\fP spawns a child process | |
95 | which should not be hold ing the lock. | |
96 | .TP | |
a120aaa7 KZ |
97 | \fB\-c\fP, \fB\-\-command\fP \fIcommand\fP |
98 | Pass a single \fIcommand\fP to the shell with \fB\-c\fP. | |
99 | .TP | |
baf39af1 KZ |
100 | \fB\-h\fP, \fB\-\-help\fP |
101 | Print a help message. | |
d162fcb5 | 102 | .SH AUTHOR |
baf39af1 KZ |
103 | Written by H. Peter Anvin <hpa@zytor.com>. |
104 | .SH COPYRIGHT | |
a120aaa7 | 105 | Copyright \(co 2003\-2006 H. Peter Anvin. |
baf39af1 KZ |
106 | .br |
107 | This is free software; see the source for copying conditions. There is NO | |
108 | warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
109 | .SH "SEE ALSO" | |
110 | .BR flock (2) | |
86d62711 KZ |
111 | .SH AVAILABILITY |
112 | The flock command is part of the util-linux-ng package and is available from | |
113 | ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/. |