halockrun(1) hatools halockrun(1)
NAME
halockrun - Run command while holding exclusive lock on file.
SYNOPSIS
halockrun [-ancfv] [-e exitcode] [-E nexitcode] lockfile command [args]
halockrun -t|-N [-nc] [-e exitcode] [-E nexitcode] lockfile
DESCRIPTION
Executes command with args while holding an exclusive lock on the file
lockfile. If the file is locked by another process, halockrun will
wait until the lock becomes available and executes the command then.
halockrun is often used to avoid cron job overruns.
halockrun uses operating system locks (POSIX -- fcntl(2)) that makes it
very resistant to stale locks.
-a Async mode. Starts command in the background. halockrun itself
exits immediately. The exitcode of the executed command is lost.
-c Create mode. Creates the lockfile if it doesn't exist. The
default behavior is to exit with exitcode if the specified lock-
file doesn't exist.
-e exitcode
Changes the exitcode returned by halockrun on fail to exitcode
The default value is 99.
-E nexitcode
Changes the "lock busy" exitcode returned by halockrun
The default value for this option is exitcode in non-blocking
mode and 1 in testing-, and noop-mode.
-n Non-blocking mode. Exits immediately with nexitcode if the lock-
file is locked by another process.
-f Fork mode. The normal behavior of halockrun is to get the lock
and call execvp(2) to execute the command specified. If fork
mode, halockrun will do a fork(2) and run the command in its own
process. In this case the parent--halockrun itself--holds the
lock on lockfile. The split in two processes opens the risk
that the parent halockrun--that holds the lock--dies and leaves
command unprotected. To minimize this risk, halockrun ignores
the following signals: TERM, HUP, INT, PIPE, QUIT, USR1, and
USR2.
This option is useful to make sure that the command does not see
any difference when running under protection of halockrun. In
other words, the fork mode makes sure that the open file handle
to lockfile is not visible to command.
Fork mode has also influence on the -t switch, because that will
not return the PID of command but of the parent halockrun
process.
This option is new to version V0.99.08, prior this version
halockrun has always fork(2)ed. The default was changed because
reliability is more important than transparency--in that case.
If you are in doubt about this option: don't use it.
-t Test mode. Checks if lockfile is currently busy, and prints the
PID of the process that holds the lock--if any. See also -N for
that purpose. The exitcode is 0 if the lock is free or nexit-
code if it is busy. Any other error--such as "lockfile not
found"--will result in exitcode.
Regardless of the lock status, halockrun will not run any com-
mand.
When the -t flags is specified the flags -a, -n and -f are mean-
ingless and will be ignored if they are specified.
-N No-op mode. The -N flag is semantically equivalent to:
halockrun lockfile /bin/true
It supplements the -t switch because it blocks. It can be com-
bined with the -n option to change the blocking behavior. How-
ever, it doesn't print the PID of the the lock holder if it is
busy.
The -N switch is more portable and used to synchronize with a
running process. The -t switch is used to obtain the PID of the
running process.
When the -N flag is specified, the -a and -f flags are meaning-
less and will be ignored if they are specified.
-v[v] Verbose mode and more verbose mode--almost debug mode.
RETURN VALUE
On success, if command was executed, halockrun returns the return value
of command.
If -t or -N was used, 0 is returned if the lock is not currently busy.
On failure--if lockfile doesn't exist or command can't be exe-
cuted--halockrun returns the value specified by the -e option.
On failure to obtain the lock in testing mode or in noop mode ( -t or
-N ) the value specified by the -E option is returned or 1 per default.
On failure to obtain the lock in non-blocking mode halockrun returns
the values specified by the -E option.
EXAMPLES
The most prominent use of halockrun is to protect from cron overrun. A
typical 5 minutes cron job like that
*/5 * * * * /path/script
would be transformed to
*/5 * * * * halockrun -cn /path/lock /path/script
This will prevent multiple parallel instances of /path/script. Addi-
tionally, you might use hatimerun to kill script when it takes longer
then 5 minutes:
*/5 * * * * hatimerun -t 5:00 halockrun -cn /path/lock /path/script
You can configure hatimerun for many different actions, please refer to
the hatimerun(1) manpage for the full documentation.
COMPATIBILITY
halockrun uses fcntl(2) advisory locking. Similar tools that use a dif-
ferent locking appraoch like flock(2) of lockf(3) may or may not work
together.
For example, locks placed by flock(2) on Linux are independend from
locks placed by fcntl(2) on the same system. That means, if you mix
those two methods, they don't lock each other.
AUTHOR
Copyright (c) 2001,2003,2005-2010 by Markus Winand <mws@fatalmind.com>
SEE ALSO
hatimerun(1)
http://www.fatalmind.com/software/hatools/
V2.14 2010-03-16 halockrun(1)
hatools 2.14 - Generated Tue Mar 16 09:15:16 CDT 2010