timeout, kill y la convención 128+señal: deducir qué mató a un proceso a partir de su código de salida

Qué es

El manual de timeout define una escala pequeña y concreta de códigos, distinta del estado de salida del propio comando:

Código	Significado
124	COMMAND superó el tiempo límite (y no se indicó --preserve-status)
125	falló el propio comando timeout
126	COMMAND se encontró, pero no se pudo invocar
127	no se pudo encontrar COMMAND
137	COMMAND (o el propio timeout) recibió SIGKILL (128+9), normalmente tras ignorar una señal anterior
—	en cualquier otro caso, se devuelve sin cambios el estado de salida del propio COMMAND

--preserve-status modifica este comportamiento: hace que timeout "exit with the same status as COMMAND, even when the command times out" (termine con el mismo estado que COMMAND, incluso cuando el comando agota el tiempo). Esto es esencial cuando quien llama necesita el código propio del programa envuelto y no el 124.

kill -0 PID no envía ninguna señal: el manual de kill(2) establece que "If sig is 0, then no signal is sent, but existence and permission checks are still performed" (si sig es 0, no se envía ninguna señal, pero se siguen realizando las comprobaciones de existencia y de permisos). Por tanto, sirve para comprobar si un PID existe y si se le pueden enviar señales (con un proceso de otro usuario falla con "Operation not permitted", aunque el PID exista). Los códigos de salida varían según la implementación: el kill de util-linux devuelve 0, 1 o 64 (éxito parcial con varios PID); el /usr/bin/kill de procps-ng (Debian/Ubuntu) devuelve 1 en caso de éxito parcial; el builtin de bash, que es el que suelen usar los scripts, devuelve 0 si se envió al menos una señal. POSIX define solo 0 (al menos una señal entregada) y >0.

La convención 128+señal permite leer la causa en un código de salida a secas. En x86/ARM (la numeración que, según el manual de señales de Linux, usan "most other architectures", es decir, la mayoría de las demás arquitecturas):

Señal	Número	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

Por qué importa

El 124 no es un fallo del programa: es timeout haciendo su trabajo. Confundirlo con un error del programa lleva a los agentes a reintentar eternamente un comando bloqueado o a reportar un timeout limpio como un misterioso bug.

Cómo aplicarlo

• Comprueba primero el 124; sin --preserve-status, cualquier código distinto de 124–127 y 137 es del propio comando. Con --preserve-status, un timeout aparece como 128+señal (143 para el TERM por defecto), nunca como 124.
• Usa kill -0 "$pid" (o kill -0 -- "$pid" para protegerte frente a valores negativos) únicamente como comprobación de existencia y permisos en bucles de sondeo; nunca como forma de terminar algo realmente.
• Cuando un proceso envuelto termina con un código 128+n, resta 128 para averiguar la señal y decide después si esa señal era esperable (un supervisor que envía SIGTERM durante el apagado) o no (SIGSEGV por un fallo real).
• Prefiere timeout --signal=TERM --kill-after=<grace> <duration> cmd, de modo que un proceso bloqueado tenga ocasión de limpiar con SIGTERM antes de que llegue el SIGKILL (137), más brusco.

Trampas

• Suponer que los números de señal son independientes de la arquitectura; el manual de Linux es explícito en que SIGBUS, SIGSTKFLT y varias más difieren entre x86/ARM, Alpha/SPARC, MIPS y PARISC.
• Tratar el código de salida 64 del kill de util-linux (éxito parcial con varios PID) como un fallo total: algunas señales sí se entregaron correctamente.