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 code 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.
35 -F, --no-fork
37 Do not fork before executing command. Upon execution the flock
38 process is replaced by command which continues to hold the lock.
39 This option is incompatible with --close as there would other‐
40 wise be nothing left to hold the lock.
41 -e, -x, --exclusive
43 Obtain an exclusive lock, sometimes called a write lock. This
44 is the default.
45 -n, --nb, --nonblock
47 Fail rather than wait if the lock cannot be immediately
48 acquired. See the -E option for the exit code used.
49 -o, --close
51 Close the file descriptor on which the lock is held before exe‐
52 cuting command. This is useful if command spawns a child
53 process which should not be holding the lock.
54 -s, --shared
56 Obtain a shared lock, sometimes called a read lock.
57 -u, --unlock
59 Drop a lock. This is usually not required, since a lock is
60 automatically dropped when the file is closed. However, it may
61 be required in special cases, for example if the enclosed com‐
62 mand group may have forked a background process which should not
63 be holding the lock.
64 -w, --wait, --timeout seconds
66 Fail if the lock cannot be acquired within seconds. Decimal
67 fractional values are allowed. See the -E option for the exit
68 code used. The zero number of seconds is interpreted as --non‐
69 block.
70 --verbose
72 Report how long it took to acquire the lock, or why the lock
73 could not be obtained.
74 -V, --version
76 Display version information and exit.
77 -h, --help
79 Display help text and exit.
80
82 shell1> flock /tmp -c cat
83 shell2> flock -w .007 /tmp -c echo; /bin/echo $?
84 Set exclusive lock to directory /tmp and the second command will
85 fail.
86 shell1> flock -s /tmp -c cat
88 shell2> flock -s -w .007 /tmp -c echo; /bin/echo $?
89 Set shared lock to directory /tmp and the second command will
90 not fail. Notice that attempting to get exclusive lock with
91 second command would fail.
92 shell> flock -x local-lock-file echo 'a b c'
94 Grab the exclusive lock "local-lock-file" before running echo
95 with 'a b c'.
96 (
98 flock -n 9 || exit 1
99 # ... commands executed under lock ...
100 ) 9>/var/lock/mylockfile
101 The form is convenient inside shell scripts. The mode used to
102 open the file doesn't matter to flock; using > or >> allows the
103 lockfile to be created if it does not already exist, however,
104 write permission is required. Using < requires that the file
105 already exists but only read permission is required.
106 [ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock -en "$0" "$0"
108 "$@" || :
109 This is useful boilerplate code for shell scripts. Put it at
110 the top of the shell script you want to lock and it'll automati‐
111 cally lock itself on the first run. If the env var $FLOCKER is
112 not set to the shell script that is being run, then execute
113 flock and grab an exclusive non-blocking lock (using the script
114 itself as the lock file) before re-execing itself with the right
115 arguments. It also sets the FLOCKER env var to the right value
116 so it doesn't run again.
117
119 The command uses sysexits.h return values for everything, except when
120 using either of the options -n or -w which report a failure to acquire
121 the lock with a return value given by the -E option, or 1 by default.
122 When using the command variant, and executing the child worked, then
124 the exit status is that of the child command.
125
127 H. Peter Anvin ⟨hpa@zytor.com⟩
128
130 Copyright © 2003-2006 H. Peter Anvin.
131 This is free software; see the source for copying conditions. There is
132 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
133 PURPOSE.
134
136 flock(2)
137
139 The flock command is part of the util-linux package and is available
140 from Linux Kernel Archive ⟨https://www.kernel.org/pub/linux/utils/util-
141 linux/⟩.
142util-linux July 2014 FLOCK(1)