timeout

Uruchamia polecenie i przerywa je po upływie zadanego czasu.

Polecenie timeout uruchamia inny program i pilnuje zegarka: jeśli program nie skończy się w wyznaczonym czasie, timeout wysyła mu sygnał i go ubija. To narzędzie z pakietu GNU coreutils, więc masz je na praktycznie każdym Linuksie bez instalowania. Przydaje się wszędzie tam, gdzie coś może się zawiesić na wieki: skrypty, healthchecki, requesty sieciowe, zadania w cronie, które nie mogą wisieć w nieskończoność.

Składnia i najważniejsze opcje

Podstawowa forma to timeout [opcje] czas polecenie [argumenty]. Czas podajesz jako liczbę z opcjonalnym sufiksem: s (sekundy, domyślnie), m (minuty), h (godziny), d (dni). Wartość 0 wyłącza limit.

  • -s, --signal=SYGNAL — sygnał wysyłany po przekroczeniu czasu (domyślnie TERM); nazwa jak HUP lub numer.
  • -k, --kill-after=CZAS — jeśli program po pierwszym sygnale dalej żyje, po tym czasie dostaje dobijające KILL.
  • -p, --preserve-status — zwraca kod wyjścia programu zamiast standardowego 124 przy timeoucie.
  • -f, --foreground — nie tworzy osobnej grupy procesów; pozwala programowi normalnie korzystać z terminala (przydatne przy pracy interaktywnej).
  • -v, --verbose — wypisuje na stderr informację, który sygnał został wysłany.
  • --help / --version — pomoc i wersja.

Przykłady użycia

  • timeout 10s ping example.com — pinguje serwer, ale przerywa dokładnie po 10 sekundach.
  • timeout 5m ./backup.sh — daje skryptowi backupu maksymalnie 5 minut, potem go ubija.
  • timeout -s KILL 30 ./upload.sh — po 30 sekundach wysyła od razu KILL zamiast łagodnego TERM.
  • timeout -k 5 20 python worker.py — daje 20 sekund, wysyła TERM, a jeśli po kolejnych 5 sekundach proces dalej działa, dobija go KILL.
  • timeout 3 curl -s https://api.example.com; echo $? — ogranicza zapytanie do 3 sekund; kod 124 oznacza, że zadziałał limit czasu.

Częste błędy i pułapki

Najczęstsza wpadka to interpretacja kodu wyjścia. Gdy timeout przerwie program, zwraca 124 — nie mylisz tego z błędem samej komendy. Jeśli chcesz poznać prawdziwy status programu, użyj --preserve-status. Kod 125 oznacza problem z samym timeout, a 126/127 — że polecenia nie dało się uruchomić lub nie znaleziono.

Druga pułapka: sam TERM nie zawsze wystarcza. Programy, które przechwytują sygnały (albo je ignorują), potrafią przeżyć timeout. Dlatego przy ważnych limitach dokładaj -k, żeby mieć pewność, że proces zginie.

Uważaj też na sposób wywołania: timeout uruchamia dokładnie jeden program. Jeśli chcesz objąć limitem cały łańcuch poleceń z potokami albo &&, opakuj to w powłokę, np. timeout 10 bash -c 'cmd1 | cmd2'. Na macOS domyślnie nie ma timeout — jest jako gtimeout po instalacji coreutils przez Homebrew.

Powiązane komendy: kill, sleep, nohup, timeout współpracuje też dobrze z xargs i watch.