TIMELIMIT(1)

💖 TIMELIMIT 💖

okay so bestie, meet timelimit(1) — the Unix tool that gives a process a deadline and actually means it 🌸 she runs your command, and the second the clock runs out, she ends it with a signal of your choosing. no cap. 👑

---

✨ NAME ✨

timelimit — effectively limit the absolute execution time of a process 🕰️

🦋 SYNOPSIS 🦋

timelimit [-pq] [-S killsig] [-s warnsig] [-T killtime] [-t warntime]
          command [arguments ...]
timelimit --features

💅 DESCRIPTION 💅

so here's the vibe: the timelimit utility runs a given command with the arguments you hand it, and after a given amount of time it terminates the process it spawned, using a given signal. and if the process exits on its own before the time limit even runs out? timelimit just quietly exits too. no drama, no notes, she simply leaves 💜

Options:

• --features — list the compile-time features this particular build of timelimit supports 👀:
  • timelimit — always there, obviously, and it comes with the version of the timelimit tool.
  • subsecond — present only if timeouts with subsecond precision are supported, with version 1.0.
• -p — if the child process gets terminated by a signal, timelimit propagates that whole situation, meaning it sends the same signal to itself. this is the slay, because it lets whatever program is running timelimit figure out whether the child was terminated by a signal or genuinely exited with an exit code bigger than 128 🔍
• -q — quiet operation. timelimit will not output diagnostic messages about the signals it sends to the child process. she's keeping it chill 🤫
• -S killsig — specify the number of the signal to send to the process killtime seconds after warntime has expired. defaults to 9 (SIGKILL) 💀
• -s warnsig — specify the number of the signal to send to the process warntime seconds after it has been started. defaults to 15 (SIGTERM) 🎀
• -T killtime — specify the maximum execution time of the process before sending killsig, after warnsig has been sent. defaults to 120 seconds ⏳
• -t warntime — specify the maximum execution time of the process in seconds before sending warnsig. defaults to 3600 seconds ⌛

on systems that support the setitimer(2) system call, the warntime and killtime values may be specified in fractional seconds with microsecond precision. yes bestie, microseconds. she's precise like that ✨

🌈 ENVIRONMENT 🌈

• KILLSIG — the killsig to use if the -S option was not specified.
• KILLTIME — the killtime to use if the -T option was not specified.
• WARNSIG — the warnsig to use if the -s option was not specified.
• WARNTIME — the warntime to use if the -t option was not specified.

🚪 EXIT STATUS 🚪

if the child process exits normally, timelimit passes its exit code right on up. if the child process is terminated by a signal and the -p flag was not specified, the exit status of timelimit is 128 plus the signal number, just like sh(1) does it. and if the -p flag was specified, timelimit raises the signal itself, so that its own parent process can in turn reliably tell the difference between a signal and an exit code larger than 128 🫶

in rare cases, timelimit may run into a system or user error; then its exit status is one of the standard sysexits(3) values:

• EX_USAGE — the command-line parameters and options were incorrectly specified. (bestie, the syntax was not syntaxing 😭)
• EX_SOFTWARE — the timelimit utility itself received an unexpected signal while waiting for the child process to terminate.
• EX_OSERR — the timelimit utility was unable to execute the child process, wait for it to terminate, or examine its exit status.

🍓 EXAMPLES 🍓

the following examples are shown as given to the shell:

timelimit -p /usr/local/bin/rsync rsync://some.host/dir /opt/mirror

run the rsync program to mirror a WWW or FTP site, and kill it if it runs longer than 1 hour (that is 3600 seconds) with SIGTERM. if the rsync process does not exit after receiving the SIGTERM, timelimit issues a SIGKILL 120 seconds after the SIGTERM. and if the rsync process is terminated by a signal, timelimit will itself raise this signal 💥

tcpserver 0 8888 timelimit -t600 -T300 /opt/services/chat/stats

start a tcpserver(n) process listening on tcp port 8888; each client connection shall invoke an instance of an IRC statistics tool under /opt/services/chat, and kill it after 600 seconds have elapsed. if the stats process is still running after the SIGTERM, it will be killed by a SIGKILL sent 300 seconds later ⏰

env WARNTIME=4.99 WARNSIG=1 KILLTIME=1.000001 timelimit sh stats.sh

start a shell script and kill it with a SIGHUP in a little under 5 seconds. if the shell gets stuck and does not respond to the SIGHUP, kill it with the default SIGKILL just a bit over a second afterwards 🙈

---

👀 SEE ALSO 👀

kill(1), rsync(1), signal(3), tcpserver(n)

📜 STANDARDS 📜

No standards documentation was harmed in the process of creating timelimit. iconic behavior, honestly 💅

💀 BUGS 💀

Please report any bugs in timelimit to the author. (she wants to know, fr fr 🫶)

👑 AUTHOR 👑

the timelimit utility was conceived and written by Peter Pentchev <roam@ringlet.net>, with contributions and suggestions by Karsten W Rohrbach <karsten@rohrbach.de>, Teddy Hogeborn <teddy@fukt.bsnet.se>, and Tomasz Nowak <nowak2000@poczta.onet.pl> 🌟

---

and that's the whole page, bestie — this one shipped with Debian, dated April 14, 2018. go forth and set some timeouts 🎀✨