1FLOCK(1) User Commands FLOCK(1)
2
6 flock - manage locks from shell scripts
7
9 flock [options] file|directory command [arguments]
10 flock [options] file|directory -c command
11 flock [options] number
12
14 This utility manages flock(2) locks from within shell scripts or from
15 the command line.
16 The first and second of the above forms wrap the lock around the execu‐
18 tion of a command, in a manner similar to su(1) or newgrp(1). They
19 lock a specified file or directory, which is created (assuming appro‐
20 priate permissions) if it does not already exist. By default, if the
21 lock cannot be immediately acquired, flock waits until the lock is
22 available.
23 The third form uses an open file by its file descriptor number. See
25 the examples below for how that can be used.
26
28 -c, --command command
29 Pass a single command, without arguments, to the shell with -c.
30 -E, --conflict-exit-code number
32 The exit status used when the -n option is in use, and the con‐
33 flicting lock exists, or the -w option is in use, and the time‐
34 out is reached. The default value is 1. The number has to be
35 in the range of 0 to 255.
36 -F, --no-fork
38 Do not fork before executing command. Upon execution the flock
39 process is replaced by command which continues to hold the lock.
40 This option is incompatible with --close as there would other‐
41 wise be nothing left to hold the lock.
42 -e, -x, --exclusive
44 Obtain an exclusive lock, sometimes called a write lock. This
45 is the default.
46 -n, --nb, --nonblock
48 Fail rather than wait if the lock cannot be immediately
49 acquired. See the -E option for the exit status used.
50 -o, --close
52 Close the file descriptor on which the lock is held before exe‐
53 cuting command. This is useful if command spawns a child
54 process which should not be holding the lock.
55 -s, --shared
57 Obtain a shared lock, sometimes called a read lock.
58 -u, --unlock
60 Drop a lock. This is usually not required, since a lock is
61 automatically dropped when the file is closed. However, it may
62 be required in special cases, for example if the enclosed com‐
63 mand group may have forked a background process which should not
64 be holding the lock.
65 -w, --wait, --timeout seconds
67 Fail if the lock cannot be acquired within seconds. Decimal
68 fractional values are allowed. See the -E option for the exit
69 status used. The zero number of seconds is interpreted as --non‐
70 block.
71 --verbose
73 Report how long it took to acquire the lock, or why the lock
74 could not be obtained.
75 -V, --version
77 Display version information and exit.
78 -h, --help
80 Display help text and exit.
81
83 The command uses sysexits.h exit status values for everything, except
84 when using either of the options -n or -w which report a failure to
85 acquire the lock with a exit status given by the -E option, or 1 by
86 default. The exit status given by -E has to be in the range of 0 to
87 255.
88 When using the command variant, and executing the child worked, then
90 the exit status is that of the child command.
91
93 Note that "shell> " in examples is a command line prompt.
94 shell1> flock /tmp -c cat
96 shell2> flock -w .007 /tmp -c echo; /bin/echo $?
97 Set exclusive lock to directory /tmp and the second command will
98 fail.
99 shell1> flock -s /tmp -c cat
101 shell2> flock -s -w .007 /tmp -c echo; /bin/echo $?
102 Set shared lock to directory /tmp and the second command will
103 not fail. Notice that attempting to get exclusive lock with
104 second command would fail.
105 shell> flock -x local-lock-file echo 'a b c'
107 Grab the exclusive lock "local-lock-file" before running echo
108 with 'a b c'.
109 (
111 flock -n 9 || exit 1
112 # ... commands executed under lock ...
113 ) 9>/var/lock/mylockfile
114 The form is convenient inside shell scripts. The mode used to
115 open the file doesn't matter to flock; using > or >> allows the
116 lockfile to be created if it does not already exist, however,
117 write permission is required. Using < requires that the file
118 already exists but only read permission is required.
119 [ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock -en "$0" "$0"
121 "$@" || :
122 This is useful boilerplate code for shell scripts. Put it at
123 the top of the shell script you want to lock and it'll automati‐
124 cally lock itself on the first run. If the env var $FLOCKER is
125 not set to the shell script that is being run, then execute
126 flock and grab an exclusive non-blocking lock (using the script
127 itself as the lock file) before re-execing itself with the right
128 arguments. It also sets the FLOCKER env var to the right value
129 so it doesn't run again.
130 shell> exec 4<>/var/lock/mylockfile
132 shell> flock -n 4
133 This form is convenient for locking a file without spawning a
134 subprocess. The shell opens the lock file for reading and writ‐
135 ing as file descriptor 4, then flock is used to lock the
136 descriptor.
137
139 H. Peter Anvin ⟨hpa@zytor.com⟩
140
142 Copyright © 2003-2006 H. Peter Anvin.
143 This is free software; see the source for copying conditions. There is
144 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
145 PURPOSE.
146
148 flock(2)
149
151 The flock command is part of the util-linux package and is available
152 from Linux Kernel Archive ⟨https://www.kernel.org/pub/linux/utils/util-
153 linux/⟩.
154util-linux July 2014 FLOCK(1)