Tema: exit-codes
-
Códigos de saída do docker/podman run: 125, 126, 127 e os códigos de sinal repassados por eles
O docker run reserva 125 para falhas do próprio Docker, 126 para um comando que não pode ser invocado e 127 para um comando não encontrado. Qualquer outro código é repassado sem alteração a partir do processo conteinerizado, inclusive os códigos 128+sinal (137 para SIGKILL, muitas vezes OOM; 139 para SIGSEGV; 143 para SIGTERM). A forma documentada de confirmar um encerramento por falta de memória é a flag OOMKilled do próprio contêiner, e não o 137 isolado, embora em alguns hosts com cgroup v2 ela apareça como false mesmo após um OOM kill do kernel.
-
Códigos de saída de find e xargs: o 0/>0 grosseiro do find versus a escala 123-127 do xargs
O find só garante 0 para sucesso total e qualquer valor acima de 0 para erro, de propósito sem mais detalhes, enquanto o xargs define uma escala específica para indicar como o comando invocado falhou: 123 para saída não zero comum, 124 para saída 255, 125 para morte por sinal, 126 para comando não executável e 127 para comando não encontrado. Encadear find com xargs num pipe significa verificar duas filosofias diferentes de código de saída no mesmo pipeline.
-
grep, diff, cmp e test/[: o código de saída 1 significa «não encontrado», não falha
grep, diff, cmp e o builtin test/[ usam a mesma escala de três valores: 0 para resultado positivo, 1 para resultado negativo que não é erro, e 2 (ou >1) para problema real. Interpretar o 1 como falha do script é o erro de leitura mais comum de um agente com essas ferramentas.
-
Códigos de saída do curl: distinguir falha de DNS, falha de TLS e --fail
O curl devolve um código numérico distinto para cada classe de falha de transporte (resolução de nome, conexão, TLS, timeout) e um código separado, 22, que só aparece quando --fail ou --fail-with-body é usado para status HTTP de erro. Um agente que avalia o código de saída do curl em vez do texto consegue direcionar as novas tentativas corretamente, sem analisar a saída.
-
timeout, kill e a convenção 128+sinal: descobrir o que encerrou um processo pelo código de saída
O GNU timeout usa 124 para o próprio timeout, 125 para falha interna, 126/127 para comando não invocável ou inexistente e 137 quando precisa escalar para SIGKILL; kill -0 verifica se um processo existe sem enviar um sinal real; e a convenção 128+número do sinal (137 = SIGKILL, 139 = SIGSEGV, 143 = SIGTERM em x86/ARM) permite a um agente identificar a causa específica a partir de um simples código de saída.
-
Códigos de saída de apt-get, dpkg, dnf e zypper: quando 100 significa atualizações disponíveis, e não falha
O apt-get usa uma divisão simples: 0 para sucesso e 100 para erro. O dpkg distingue uma verificação que falhou (1) de um erro fatal de uso ou de sistema (2). No check-update do dnf, 100 indica que HÁ atualizações disponíveis, e não um erro. O zypper define toda uma faixa, de 100 a 107, de códigos informativos (que não são erros), como a necessidade de reiniciar, embora 104 (pacote não encontrado) e 105 (interrompido) signifiquem que a ação não foi executada. Tratar qualquer um deles como um simples booleano de sucesso ou falha faz perder informação relevante.
-
Códigos de saída de ssh e scp: 255 é falha do próprio ssh, qualquer outro valor vem do comando remoto
O ssh repassa o código de saída do comando remoto que executou e reserva o 255 para falhas do próprio ssh (conexão recusada, falha de autenticação, host key divergente) e para comando remoto morto por um sinal. O scp documenta apenas a divisão simples entre 0 (sucesso) e diferente de zero (falha); por isso, para distinguir problemas locais de transporte de um erro remoto, é preciso usar o texto de stderr do ssh, e não o código do scp.
-
Códigos de saída no Windows além de sucesso/falha: o bitmask do robocopy, os códigos do instalador do msiexec e $LASTEXITCODE
O robocopy codifica vários fatos independentes (arquivos copiados, arquivos extras, divergências, falhas) em um único número abaixo de 8, que deve ser lido como bitmask e não comparado com zero. O msiexec devolve códigos específicos do Windows Installer, em que 3010 e 1641 significam sucesso com reinicialização pendente, e não falha. No PowerShell, $LASTEXITCODE é a única forma confiável de ver o código real de um programa nativo, com regras que variam conforme o modo de invocação do script.
-
Códigos de saída do wget e do rsync: os códigos 23 e 24 do rsync geralmente não são a falha que parecem
O wget atribui um código fixo e pequeno a cada classe de erro (rede, SSL, autenticação, protocolo); a tabela do rsync é maior e inclui o 23 (transferência parcial por erro) e o 24 (transferência parcial por arquivos de origem que desapareceram), que geralmente só indica que um arquivo sumiu durante a varredura, sem evidenciar uma transferência com problema.
-
Códigos de saída do git em que um agente pode confiar: diff --exit-code, ls-remote --exit-code e o 125 do bisect run
A maioria dos comandos porcelain do git documenta apenas «código diferente de zero em caso de falha», sem tabela numérica fixa, mas três comandos têm um contrato exato e citável: git diff/--quiet usa 1 para diferenças, git ls-remote --exit-code usa 2 quando não há refs correspondentes, e git bisect run reserva o 125 para «ignorar este commit», não para «ruim». Um merge com conflito é indicado por estado (MERGE_HEAD), não por um número documentado.
-
make, ping e nc: códigos de saída que, silenciosamente, não verificam o que você imagina
No GNU make, o código de saída 1 de -q significa "um alvo precisa ser reconstruído", não falha. No ping, o código 1 indica que nenhuma resposta foi recebida (host fora do ar, não uma chamada quebrada do ping) e o 2 indica um erro real, de uso ou de outro tipo. A documentação do openssl s_client diz que, por padrão, a conexão termina com sucesso (código 0) mesmo quando a verificação do certificado falhou, a menos que -verify_return_error seja usado.
-
Códigos de saída do systemctl: is-active, is-enabled, is-failed e o que significa o código LSB 3
Os subcomandos is-active, is-enabled e is-failed do systemctl documentam um contrato simples de 0 contra não zero (na prática com valores no estilo LSB, como 3 para inativo e 4 para unit desconhecida), enquanto systemctl status segue a antiga convenção dos scripts init LSB, em que 3 significa «não está em execução» e não um erro de execução. Ler 3 ou 4 como uma chamada com defeito é a principal forma de agentes interpretarem mal o systemctl.
-
Códigos de saída como contrato entre scripts e o agente que os chama
Um agente que executa um script e decide o próximo passo pelo código de saída precisa que esse código tenha o significado das convenções do shell: 0 para sucesso, números positivos pequenos para as falhas definidas pelo próprio script, 126/127 para um comando que não pôde ser executado e 128+n para término por sinal. Além disso, precisa de pipefail ou PIPESTATUS para enxergar o código real através de um pipeline.
Legível por máquina: JSON