timeout, kill and the 128+signal convention: reading what killed a process from its exit code

What it is

timeout's manual defines a small, specific ladder distinct from the command's own exit status:

Code	Meaning
124	COMMAND timed out (and --preserve-status was not given)
125	the timeout command itself failed
126	COMMAND was found but could not be invoked
127	COMMAND could not be found
137	COMMAND (or timeout itself) was sent SIGKILL (128+9), typically after ignoring an earlier signal
—	otherwise, COMMAND's own exit status is returned unchanged

--preserve-status changes this: it makes timeout "exit with the same status as COMMAND, even when the command times out," which is essential when the caller needs the wrapped program's own code rather than 124.

kill -0 PID does not send a signal at all — the kill(2) manual states "If sig is 0, then no signal is sent, but existence and permission checks are still performed," so it probes whether a PID exists and is signalable (for another user's process it fails with "Operation not permitted" although the PID exists). Exit codes differ by implementation: util-linux kill returns 0, 1 or 64 (partial success across several PIDs); procps-ng's /usr/bin/kill (Debian/Ubuntu) returns 1 on partial success; the bash builtin, which scripts usually get, returns 0 if at least one signal was sent. POSIX defines only 0 (at least one signal delivered) and >0.

The 128+signal convention lets you read the cause from a bare exit code. On x86/ARM (the numbering used by "most other architectures" per the Linux signal manual):

Signal	Number	128+n
SIGHUP	1	129
SIGINT	2	130
SIGQUIT	3	131
SIGABRT	6	134
SIGKILL	9	137
SIGSEGV	11	139
SIGPIPE	13	141
SIGTERM	15	143

Why it matters

124 is not a crash — it is timeout doing its job. Conflating it with a program failure makes agents retry a hung command forever or report a clean timeout as a mysterious bug.

How to apply

• Check for 124 first; without --preserve-status, any code other than 124–127 and 137 is the command's own. With --preserve-status, a timeout shows up as 128+signal (143 for the default TERM), never 124.
• Use kill -0 "$pid" (or kill -0 -- "$pid" for negative-safety) purely as an existence/permission probe in polling loops — never as a way to actually terminate anything.
• When a wrapped process exits with a 128+n code, subtract 128 to look up the signal, then decide whether that signal is expected (a supervisor sending SIGTERM during shutdown) or not (SIGSEGV from a genuine crash).
• Prefer timeout --signal=TERM --kill-after=<grace> <duration> cmd so a hung process gets a chance to clean up under SIGTERM before the harsher SIGKILL (137) arrives.

Pitfalls

• Assuming signal numbers are architecture-independent; the Linux manual is explicit that SIGBUS, SIGSTKFLT and several others differ between x86/ARM, Alpha/SPARC, MIPS and PARISC.
• Treating util-linux kill's exit code 64 (partial success across multiple PIDs) as a full failure — some signals were delivered successfully.