1FLOCK(1) User Commands FLOCK(1)
2
6 flock - manage locks from shell scripts
7
9 flock [options] <file|directory> <command> [command args]
10 flock [options] <file|directory> -c <command>
11 flock [options] <file descriptor number>
12
14 This utility manages flock(2) locks from within shell scripts or the
15 command line.
16 The first and second forms wrap the lock around the executing a com‐
18 mand, in a manner similar to su(1) or newgrp(1). It locks a specified
19 file or directory, which is created (assuming appropriate permissions),
20 if it does not already exist. By default, if the lock cannot be imme‐
21 diately acquired, flock waits until the lock is available.
22 The third form uses open file by file descriptor number. See examples
24 how that can be used.
25
27 -s, --shared
28 Obtain a shared lock, sometimes called a read lock.
29 -x, -e, --exclusive
31 Obtain an exclusive lock, sometimes called a write lock. This
32 is the default.
33 -u, --unlock
35 Drop a lock. This is usually not required, since a lock is
36 automatically dropped when the file is closed. However, it may
37 be required in special cases, for example if the enclosed com‐
38 mand group may have forked a background process which should not
39 be holding the lock.
40 -n, --nb, --nonblock
42 Fail rather than wait if the lock cannot be immediately
43 acquired. See the -E option for the exit code used.
44 -w, --wait, --timeout seconds
46 Fail if the lock cannot be acquired within seconds. Decimal
47 fractional values are allowed. See the -E option for the exit
48 code used. The zero number of seconds is interpreted as --non‐
49 block.
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 -E, --conflict-exit-code number
57 The exit code used when the -n option is in use, and the con‐
58 flicting lock exists, or the -w option is in use, and the time‐
59 out is reached. The default value is 1.
60 -c, --command command
62 Pass a single command, without arguments, to the shell with -c.
63 -h, --help
65 Print a help message.
66 -V, --version
68 Show version number and exit.
69
71 shell1> flock /tmp -c cat
72 shell2> flock -w .007 /tmp -c echo; /bin/echo $?
73 Set exclusive lock to directory /tmp and the second command will
74 fail.
75 shell1> flock -s /tmp -c cat
77 shell2> flock -s -w .007 /tmp -c echo; /bin/echo $?
78 Set shared lock to directory /tmp and the second command will
79 not fail. Notice that attempting to get exclusive lock with
80 second command would fail.
81 shell> flock -x local-lock-file echo 'a b c'
83 Grab the exclusive lock "local-lock-file" before running echo
84 with 'a b c'.
85 (
87 flock -n 9 || exit 1
88 # ... commands executed under lock ...
89 ) 9>/var/lock/mylockfile
90 The form is convenient inside shell scripts. The mode used to
91 open the file doesn't matter to flock; using > or >> allows the
92 lockfile to be created if it does not already exist, however,
93 write permission is required. Using < requires that the file
94 already exists but only read permission is required.
95 [ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock -en "$0" "$0"
97 "$@" || :
98 This is useful boilerplate code for shell scripts. Put it at
99 the top of the shell script you want to lock and it'll automati‐
100 cally lock itself on the first run. If the env var $FLOCKER is
101 not set to the shell script that is being run, then execute
102 flock and grab an exclusive non-blocking lock (using the script
103 itself as the lock file) before re-execing itself with the right
104 arguments. It also sets the FLOCKER env var to the right value
105 so it doesn't run again.
106
108 The command uses sysexits.h return values for everything else but an
109 options -n or -w failures which return either the value given by the -E
110 option, or 1 by default.
111
113 H. Peter Anvin ⟨hpa@zytor.com⟩
114
116 Copyright © 2003-2006 H. Peter Anvin.
117 This is free software; see the source for copying conditions. There is
118 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
119 PURPOSE.
120
122 flock(2)
123
125 The flock command is part of the util-linux package and is available
126 from Linux Kernel Archive ⟨ftp://ftp.kernel.org/pub/linux/utils/util-
127 linux/⟩.
128util-linux September 2011 FLOCK(1)