timeout, kill e a convenção 128+sinal: descobrir o que encerrou um processo pelo código de saída

O que é

O manual do timeout define uma pequena escala específica de códigos, distinta do status de saída do próprio comando:

Código	Significado
124	COMMAND excedeu o tempo limite (e --preserve-status não foi usado)
125	o próprio comando timeout falhou
126	COMMAND foi encontrado, mas não pôde ser invocado
127	COMMAND não foi encontrado
137	COMMAND (ou o próprio timeout) recebeu SIGKILL (128+9), normalmente após ignorar um sinal anterior
—	nos demais casos, o status de saída do próprio COMMAND é retornado sem alteração

--preserve-status muda esse comportamento: faz o timeout "exit with the same status as COMMAND, even when the command times out" (sair com o mesmo status de COMMAND, mesmo quando o comando excede o tempo limite), o que é essencial quando quem chama precisa do código do programa encapsulado e não do 124.

kill -0 PID não envia sinal algum. O manual de kill(2) afirma: "If sig is 0, then no signal is sent, but existence and permission checks are still performed" (se sig for 0, nenhum sinal é enviado, mas as verificações de existência e de permissão continuam sendo feitas). Ou seja, ele testa se um PID existe e se é possível enviar-lhe sinais (para o processo de outro usuário, falha com "Operation not permitted", embora o PID exista). Os códigos de saída variam conforme a implementação: o kill do util-linux retorna 0, 1 ou 64 (sucesso parcial com vários PIDs); o /usr/bin/kill do procps-ng (Debian/Ubuntu) retorna 1 em caso de sucesso parcial; o builtin do bash, que é o que os scripts costumam usar, retorna 0 se pelo menos um sinal foi enviado. O POSIX define apenas 0 (pelo menos um sinal entregue) e >0.

A convenção 128+sinal permite ler a causa a partir de um código de saída isolado. Em x86/ARM (a numeração usada por "most other architectures" — a maioria das outras arquiteturas —, segundo o manual de sinais do Linux):

Sinal	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 que importa

124 não é uma falha: é o timeout fazendo o seu trabalho. Confundi-lo com uma falha do programa leva agentes a repetir indefinidamente um comando travado ou a reportar como bug misterioso um timeout perfeitamente normal.

Como aplicar

• Verifique primeiro o 124. Sem --preserve-status, qualquer código fora de 124–127 e 137 pertence ao próprio comando. Com --preserve-status, o timeout aparece como 128+sinal (143 para o TERM padrão), nunca como 124.
• Use kill -0 "$pid" (ou kill -0 -- "$pid", por segurança contra valores negativos) apenas como sonda de existência/permissão em loops de polling, nunca para realmente encerrar algo.
• Quando um processo encapsulado sai com um código 128+n, subtraia 128 para descobrir o sinal e depois decida se esse sinal era esperado (um supervisor enviando SIGTERM durante o desligamento) ou não (SIGSEGV causado por um crash real).
• Prefira timeout --signal=TERM --kill-after=<grace> <duration> cmd, para que um processo travado tenha a chance de fazer a limpeza ao receber SIGTERM antes de chegar o SIGKILL (137), mais drástico.

Armadilhas

• Presumir que os números dos sinais são independentes da arquitetura; o manual do Linux é explícito ao dizer que SIGBUS, SIGSTKFLT e vários outros diferem entre x86/ARM, Alpha/SPARC, MIPS e PARISC.
• Tratar o código de saída 64 do kill do util-linux (sucesso parcial com vários PIDs) como falha total: alguns sinais foram entregues com sucesso.