1WITHLOCK(1) WITHLOCK(1)
2
6 withlock - locking wrapper script
7
9 withlock lockfile command [args...]
10 withlock [-w <seconds>|--wait=seconds] [-q|--quiet] [-v|--verbose]
11 lockfile command [args...]
12 withlock [-h|--help]
13 withlock [--version]
14
16 withlock(1) is a wrapper script to make sure that some program isn´t
17 run more than once. It is ideal to prevent periodic jobs spawned by
18 cron(8) from stacking up.
19 It uses locks that are valid only while the wrapper is running, and
21 thus will never require additional cleanup, even after a system crash
22 or reboot. This makes the wrapper safe and easy to use, and better than
23 implementing half-hearted locking within scripts.
24 The script can wait a defined time for a lock to become "free".
26
28 Lockfiles, generally, MUST NOT be placed in a publicly writable direc‐
29 tory, because that would allow for a symlink attack. For that reason,
30 withlock(1) simply disallows lockfiles in such locations.
31
33 -v, --verbose
34 Print debug messages to stderr.
35 -q, --quiet
37 If lock can´t be acquired immediately, silently quit without
38 error.
39 --version
41 Show program´s version number and exit.
42 -h, --help
44 Show command synopsis and exit.
45 -w seconds, --wait=seconds
47 Wait for maximum seconds for the lock to be acquired.
48
50 Instead of your command
51 <command> [<args>...]
55 you simply use
59 withlock <lockfile> <command> [<args>...]
63 cron(8) jobs, especially long running ones, are frequently run under
67 withlock(1). Here´s an example:
68 -*/10 * * * * root withlock LOCK-serverstatus /usr/bin/log_server_status2
72 43 5,17 * * * mirror withlock LOCK-rsync-edu-isos rsync -rlptoH --no-motd rsync.opensuse-education.org::download/ISOs/ /srv/mirrors/opensuse-education/ISOs -hi
73
77 This wrapper was implemented because no comparable solution was found
78 even after looking around for a long time (and suffering problems
79 caused by missing or insufficient locking for years). The only solution
80 that comes close is with-lock-ex.c, an implementation in C, which was
81 written by Ian Jackson and placed in the public domain by him.
82 with-lock-ex.c is traditionally available on Debian in a package named
83 chiark-utils-bin. Parts of withlock´s locking strategy and parts of the
84 usage semantics were inspired from that program. This implementation
85 was chosen to be done in Python because it´s universally available,
86 easy to adapt, and doesn´t require to be compiled.
87 Then, somebody pointed out to me that there´s flock(1), a small tool
89 written in C that does the same. Indeed, I had apparently managed to
90 miss that tool during a decade´s worth of Linux hacking (you discover
91 something new every day, don´t you?). The functionality is mainly the
92 same indeed.
93 However, withlock(1) has some advantages:
95 · withlock(1) ist a little easier and logical to use than flock(1).
97 The semantics are more suited for sysadmins.
98 · withlock(1) always cleans up it´s lock files. flock(1) always lets
100 them lying around. I admit that I like the fact that with with‐
101 lock(1) I can always see by the presence of the lock files which
102 jobs are running.
103 · flock(1) doesn´t prevent using unsafe directories
105 · withlock(1) is easily extensible
107 · it could be used as a Python module (not implemented so far)
109 · flock(1) doesn´t exist on Solaris and OSX
111
115 withlock(1) has been tested on many platforms, including Debian,
116 Ubuntu, openSUSE, CentOS, Fedora, FreeBSD, OSX, OpenCSW Solaris and is
117 in production use since 2009. There don´t seem to be race conditions
118 (the author tried very hard to break it) but there are no guarantees.
119
121 This program was written by Peter Pöml peter@poeml.de in 2009.
122
124 flock(1)
125 with-lock-ex(1) from Debian package chiark-utils-bin
126 June 2015 WITHLOCK(1)