1halockrun(1) hatools halockrun(1)
2
6 halockrun - Run command while holding exclusive lock on file.
7
9 halockrun [-ancfv] [-e exitcode] [-E nexitcode] lockfile command [args]
10 halockrun -t|-N [-nc] [-e exitcode] [-E nexitcode] lockfile
11
13 Executes command with args while holding an exclusive lock on the file
14 lockfile. If the file is locked by another process, halockrun will
15 wait until the lock becomes available and executes the command then.
16 halockrun is often used to avoid cron job overruns.
18 halockrun uses operating system locks (POSIX -- fcntl(2)) that makes it
20 very resistant to stale locks.
21 -a Async mode. Starts command in the background. halockrun itself
24 exits immediately. The exitcode of the executed command is lost.
25 -c Create mode. Creates the lockfile if it doesn't exist. The
27 default behavior is to exit with exitcode if the specified lock‐
28 file doesn't exist.
29 -e exitcode
31 Changes the exitcode returned by halockrun on fail to exitcode
32 The default value is 99.
33 -E nexitcode
36 Changes the "lock busy" exitcode returned by halockrun
37 The default value for this option is exitcode in non-blocking
39 mode and 1 in testing-, and noop-mode.
40 -n Non-blocking mode. Exits immediately with nexitcode if the lock‐
43 file is locked by another process.
44 -f Fork mode. The normal behavior of halockrun is to get the lock
46 and call execvp(2) to execute the command specified. If fork
47 mode, halockrun will do a fork(2) and run the command in its own
48 process. In this case the parent--halockrun itself--holds the
49 lock on lockfile. The split in two processes opens the risk
50 that the parent halockrun--that holds the lock--dies and leaves
51 command unprotected. To minimize this risk, halockrun ignores
52 the following signals: TERM, HUP, INT, PIPE, QUIT, USR1, and
53 USR2.
54 This option is useful to make sure that the command does not see
56 any difference when running under protection of halockrun. In
57 other words, the fork mode makes sure that the open file handle
58 to lockfile is not visible to command.
59 Fork mode has also influence on the -t switch, because that will
61 not return the PID of command but of the parent halockrun
62 process.
63 This option is new to version V0.99.08, prior this version
65 halockrun has always fork(2)ed. The default was changed because
66 reliability is more important than transparency--in that case.
67 If you are in doubt about this option: don't use it.
69 -t Test mode. Checks if lockfile is currently busy, and prints the
71 PID of the process that holds the lock--if any. See also -N for
72 that purpose. The exitcode is 0 if the lock is free or nexit‐
73 code if it is busy. Any other error--such as "lockfile not
74 found"--will result in exitcode.
75 Regardless of the lock status, halockrun will not run any com‐
77 mand.
78 When the -t flags is specified the flags -a, -n and -f are mean‐
80 ingless and will be ignored if they are specified.
81 -N No-op mode. The -N flag is semantically equivalent to:
83 halockrun lockfile /bin/true
85 It supplements the -t switch because it blocks. It can be com‐
87 bined with the -n option to change the blocking behavior. How‐
88 ever, it doesn't print the PID of the the lock holder if it is
89 busy.
90 The -N switch is more portable and used to synchronize with a
92 running process. The -t switch is used to obtain the PID of the
93 running process.
94 When the -N flag is specified, the -a and -f flags are meaning‐
96 less and will be ignored if they are specified.
97 -v[v] Verbose mode and more verbose mode--almost debug mode.
100
103 On success, if command was executed, halockrun returns the return value
104 of command.
105 If -t or -N was used, 0 is returned if the lock is not currently busy.
107 On failure--if lockfile doesn't exist or command can't be exe‐
109 cuted--halockrun returns the value specified by the -e option.
110 On failure to obtain the lock in testing mode or in noop mode ( -t or
112 -N ) the value specified by the -E option is returned or 1 per default.
113 On failure to obtain the lock in non-blocking mode halockrun returns
115 the values specified by the -E option.
116
119 The most prominent use of halockrun is to protect from cron overrun. A
120 typical 5 minutes cron job like that
121 */5 * * * * /path/script
123 would be transformed to
125 */5 * * * * halockrun -cn /path/lock /path/script
127 This will prevent multiple parallel instances of /path/script. Addi‐
129 tionally, you might use hatimerun to kill script when it takes longer
130 then 5 minutes:
131 */5 * * * * hatimerun -t 5:00 halockrun -cn /path/lock /path/script
133 You can configure hatimerun for many different actions, please refer to
135 the hatimerun(1) manpage for the full documentation.
136
139 halockrun uses fcntl(2) advisory locking. Similar tools that use a dif‐
140 ferent locking appraoch like flock(2) of lockf(3) may or may not work
141 together.
142 For example, locks placed by flock(2) on Linux are independend from
144 locks placed by fcntl(2) on the same system. That means, if you mix
145 those two methods, they don't lock each other.
146
148 Copyright (c) 2001,2003,2005-2010 by Markus Winand <mws@fatalmind.com>
149
151 hatimerun(1)
152 http://www.fatalmind.com/software/hatools/
154V2.14 2010-03-16 halockrun(1)