halockrun(1)

📦 version 2.14, in fedora 43, fedora 44

🦋 NAME 🦋

okay so bestie, meet halockrun — part of the hatools crew, manual section 1. Its whole entire job? Run a command while holding an exclusive lock on a file. That's it. That's the girl. 💅

✨ SYNOPSIS ✨

halockrun [-ancfv] [-e exitcode] [-E nexitcode] lockfile command [args]
halockrun -t|-N [-nc] [-e exitcode] [-E nexitcode] lockfile

💖 DESCRIPTION 💖

So basically, halockrun runs command with args while it's holding an exclusive lock on the file lockfile. If the file is already locked by another process, halockrun ®.I command then.

bestie I'm not even kidding, the original page literally says halockrun ®.I command then. — that's a groff formatting artifact that fell out of the source, and I am NOT about to invent behavior for you. Keeping it exactly as-is because facts are sacred. 🙈

halockrun is often used to avoid cron job overruns.

It uses operating system locks (POSIX — fcntl(2)) which makes it very resistant to stale locks. periodt.

  • -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. That's not me being dramatic, that's the manpage being dramatic. 💀
  • -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. It's just peeking, not touching. 👀

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 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. mixing them = chaos, and not the cute kind. 💀

👑 AUTHOR 👑

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

🌸 SEE ALSO 🌸

and that's the whole page bestie, no cap. this was V2.14, dated 2010-03-16, straight out of the hatools bag 🫶 go lock something responsibly 💖🎀

📦 where this page comes from