halockrun

Langue: en

Version: $Date: 2007/08/18 15:38:13 $ (fedora - 04/07/09)

Section: 1 (Commandes utilisateur)

NAME

halockrun - Run command while hold exclusive lock on file.

SYNOPSIS

halockrun [-ancf] [-e exitcode] [-E nexitcode] lockfile command [args]

halockrun -t [-c] [-e exitcode] [-E nexitcode] lockfile

DESCRIPTION

Executes the given command with the given args while holding an exclusive lock on the file lockfile . If the file is already locked by another Process halockrun will wait until the lock was released and execute the command afterwards.

This is useful to serialize command execution from a shell script.

halockrun is implemented using locks from the operating system which makes it very reliable and not vulnerable to dead locks.

halockrun can also be used to implement start/stop script's without having pid-files.

-a
Async mode. Starts the command in the background. The hatimerun program exits immediately. The returncode 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 for this option is 99

-E nexitcode
Changes the exitcode returned by halockrun in nonblocking or testing mode if the lock can't be obtained to nexitcode

The default value for this option is exitcode in nonblocking mode and 1 in testing mode.

-n
Nonblocking mode. Exits 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 this option is specified, 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 the lockfile. This may cause some troubles if the halockrun process dies and the child is not finished yet, in that case the child would not be protected. To minimize this risk the halockrun process holding the lock ignores the following signals: TERM, HUP, INT, PIPE, QUIT, USR1 and USR2.

This option is only useful to make sure that the command does not see any difference when running under protection of halockrun. The only thing which is different (currently) when not running with the -f option is that there is another open filehandle which is connected to the lockfile and holds the lock.

This option is new to version V0.99.08, before this version halockrun has always made a fork. The default has changed because it is much more important to make sure to not lose the lock by accident then to make halockrun 100% transparent.

If you are in doubt about this option: don't use it.

-t
Test mode. Can be used to check if the lockfile is currently locked. If you specify this option halockrun will check if the file is locked and return 0 if it is not locked or nexitcode if it is locked and will print the pid of the process which holds the lock to stdout. Regardless of the lockstatus, halockrun will not run any command.

If an error occurs (e.g. because the lockfile doesn't exists) exitcode will be returned.

Please note that if another halockrun is currently holing the lock, you will receive the pid of the halockrun process which holds the lock. This is usually the program which you run under protection of halockrun but might be the halockrun process itself if you have specified the -f flag.

When the -t flags is specified the flags -a, -n and -f are meaningless and will be ignored if the are specified.

RETURN VALUE

On success (if the command was executed) halockrun returns the returnvalue of the given command

On fail (e.g. if the lockfile doesn't exist or the 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 nonblocking mode halockrun returns the values specified by the -E option.

AUTHOR

Copyright (c) 2001,2003,2005-2007 by Markus Winand <mws@fatalmind.com>

SEE ALSO

hatimerun(1)