halockrun

 

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 command then.

halockrun is often used to avoid cron job overruns.

halockrun uses operating system locks (POSIX -- (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 lockfile 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 lockfile 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 nexitcode 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 command.

When the -t flags is specified the flags -a, -n and -f are meaningless 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 combined with the -n option to change the blocking behavior. However, 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 meaningless 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 executed--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. Additionally, 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 different 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 <>  

SEE ALSO

hatimerun(1)