hatimerun(1)

okay bestie, sit down, hydrate 💖 this is hatimerun(1), a page straight out of the hatools manual, and it's literally the timeout queen of your process table 👑

---

🌸 NAME 🌸

hatimerun — Run command with a timeout. that's it, that's the whole job, and she does it flawlessly 💅

---

✨ SYNOPSIS ✨

hatimerun [-av] [-e exitcode] [-k sig] -t [[hh:]mm:]secs command [args]
hatimerun [-l|-h|-?]

---

💅 DESCRIPTION 💅

So the whole thing is: she runs command args with a timeout of [[hh:]mm:]secs seconds. If command is still being dramatic and hasn't terminated before the timeout hits, hatimerun sends a signal to command. no cap 🫶

Command gets started in its own process group, and guess what — the signal gets sent to the process group. group chat behaviour fr fr 😌

Here's the iconic part: hatimerun herself will not terminate while command is running — not even if the timeout already happened. She terminates when command terminates. main character waits for her friend, always 🥹

She can also be configured to send a sequence of different signals to command, so you get a graceful termination and still get a hard timeout with the KILL signal at the end. peek the EXAMPLES below for the tea 🍓

hatimerun herself ignores these signals so nobody can prematurely end her: TERM, HUP, INT, PIPE, QUIT, USR1 and USR2. she's unbothered, moisturized, in her lane ✨

---

• -t [[hh:]mm:]secs — the timeout, periodt. specifies the time when the signal is sent, if command didn't terminate before that. you can pass multiple -t and that's fully supported — every time a specified timeout happens, a new signal is sent to the child. see EXAMPLES 👇
• -k sig — picks the signal that gets sent on timeout. multiple -k occurrences are supported so you can set different signals for different timeouts, iykyk: the second -k signal goes out on the second timeout, and so on. and if there are fewer -k arguments than timeouts (-t), hatimerun sends SIGKILL at the additional timeouts. see EXAMPLES below 💀 symbolic and numeric signal specs are both accepted. the "magic" signal name NONE sends no signal at all, which is lowkey perfect in combination with -v.

Default: SIGKILL

• -e exitcode — changes the exit code hatimerun returns on timeout. this code kicks in as soon as the first timeout has passed, irrespective of the exit status of command. multiple -e occurrences are supported in connection with multiple -t occurrences.

Default: 99

• -a — starts hatimerun in the background. hatimerun herself exits immediately. the exit code of command is lost. gone. no thoughts head empty 🙈
• -l — prints the list of available symbolic signal names on this platform and exits. very helpful, very demure 🎀
• -v — verbose mode. prints a message containing the runtime if the first timeout passed before command terminated. super useful in cron so you actually get an e-mail sent when a timeout has passed by. you can pair this with the -k NONE switch to just print an error message on timeout and not kill command. gentle queen 🌸
• -vv — more verbose mode, basically almost debug mode. writes a status message on every timeout. she's telling you everything 👀
• -h | -? — prints a help screen and exits 🫶

---

🔥 RETURN VALUE 🔥

If the command terminates normally before the first timeout happened: on success, hatimerun returns the return value of the given command. slay, business as usual ✨

After the first timeout has happened, hatimerun returns the value specified by the respective -e option, or 99 per default. and listen — hatimerun will always wait for the program to terminate. even if the program terminates normally after the first signal was sent, hatimerun will return the respective error code as its return value, and the exit code of the command is lost. that code is not coming back bestie, it's gone 💀

---

🌈 EXAMPLES 🌈

the classic:

hatimerun -t 5 sleep 10

Will kill the sleep command after 5 seconds. bye 👋

---

the gentle one:

hatimerun -k TERM -t 5 sleep 10

Will send the TERM signal after 5 seconds.

---

the two-step, graceful-then-nuclear:

hatimerun -k TERM -t 5 -e 100 -e 101 -t 1 sleep 10

Will send the TERM signal after 5 seconds, and (if the command didn't finish till then) send the KILL signal one second later — about 6 seconds after program start. Will return 100 if the program was terminated by the TERM signal, or 101 if it was terminated by the KILL signal. the escalation timeline 💅

---

the patient one:

hatimerun -k HUP -t 1 nohup sleep 1000

Will send a HUP signal after one second and then wait (potentially forever) until the child terminates. she said take your time 🥹

---

the "yes, you can do minutes" one:

hatimerun -k TERM -t 1:30 sleep 120

Will send the TERM signal after one minute and 30 seconds (90 seconds). math ate, no crumbs 🧮

---

👑 AUTHOR 👑

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

---

🦋 SEE ALSO 🦋

halockrun(1) — her sister, go say hi 🫶

---

Version V2.14, dated 2010-03-16 — that's the whole page bestie, go forth and timeout responsibly 💖✨🎀🦋