halockrun

 

NAME

halockrun - Run command while hold exclusive lock on file.  

SYNOPSIS

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

halockrun -t|-N [-nc] [-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 non-blocking or testing mode if the lock can't be obtained to nexitcode

The default value for this option is exitcode in non-blocking mode and 1 in testing mode and noop mode.

-n

Non-blocking 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 file-handle 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 retrieve the PID of the process currently holding the lock (if any), compare also -N for that purpose. 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 lock status, halockrun will not run any command.

If an error occurs (e.g. because 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 they are specified.

-N

No-op mode. Can be used to check if lockfile is currently locked. In difference to the -t flag, the PID of the process will not be returned. Using the -N flag is semantically equivalent to running:

halockrun lockfile /bin/true

and the implementation is more portable then the -t implementation.

If you just need to know if the lockfile is currently busy but don't need the PID of the lock holder, prefer -N over -t for portability reasons.

This option can be combined with the -n option to not block until the lockfile becomes available so that halockrun will behave like in test-mode (but not print anything to stdout). Using -N without -n can be used to cause halockrun to block until the lockfile becomes available.

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

 

RETURN VALUE

On success (if the command was executed) halockrun returns the return value of the given command or 0 if -t or -N was used.

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

 

AUTHOR

Copyright (c) 2001,2003,2005-2009 by Markus Winand <>  

SEE ALSO

hatimerun(1)