Códigos de saída explicados

O que é um código de saída

Quando um programa termina, ele entrega ao sistema um único número entre 0 e 255. Zero significa que deu certo. Qualquer outra coisa significa que não deu, e isso é quase tudo o que está garantido. O shell guarda esse número na variável escrita com um ponto de interrogação, sistemas de integração contínua o imprimem quando uma etapa falha, e runtimes de contêiner o relatam quando algo para.

Quase toda tabela de códigos de saída na web apresenta uma lista única e plana — 0 sucesso, 1 erro geral, 2 uso indevido de builtins, 64 a 78 do sysexits, 126, 127, 128 mais o número do sinal — como se um único padrão dissesse tudo isso. Lendo os documentos de verdade, essas linhas vêm de quatro lugares diferentes, e uma das mais citadas não vem de lugar nenhum. Esta página decodifica um código e diz, para cada leitura, qual documento está por trás dela.

A distinção não é preciosismo. É a diferença entre uma regra que você pode esperar que outro programa cumpra e um hábito que por acaso é comum no canto do mundo onde você aprendeu.

Como usar

1. Digite o número. O que o seu log de CI, o runtime de contêineres ou o shell reportou. Os botões cobrem os que mais aparecem.
2. Leia todas as leituras, não só a primeira. Um mesmo número pode ser várias coisas ao mesmo tempo: 64 é tanto um código do sysexits quanto um número qualquer que um programa escolheu por conta própria, e mostrar só uma das duas seria afirmar algo que as fontes não sustentam.
3. Repare em quem define. Cada leitura vem rotulada como POSIX, manual do Bash, sysexits.h ou nenhum padrão. Esse rótulo é a parte que vale guardar.

Quais números são de fato especificados

O POSIX, no capítulo sobre a linguagem do shell, fixa muito pouco: zero para sucesso, 127 quando um comando não é encontrado e 126 quando é encontrado mas não pode ser executado. Esses três valem em qualquer lugar. Para um programa morto por um sinal ele diz apenas que o código será maior que 128 e identificará o sinal de uma maneira definida pela implementação — não diz 128 mais o número do sinal.

Essa última parte surpreende, porque 128 mais o número do sinal é exatamente o que acontece. Está no manual do Bash, e não no POSIX: o bash declara que, quando um comando termina por um sinal fatal N, ele usa 128+N. Medido aqui com bash, dash e o shell do sistema, os três concordaram: um processo morto por SIGTERM devolveu 143, por SIGKILL 137, por SIGINT 130 e por SIGHUP 129. É confiável na prática, e é a promessa de um shell, não a do padrão.

O bash também define o 2, mas de forma bem mais estreita do que as tabelas sugerem: todos os seus builtins devolvem 2 para indicar uso incorreto, como uma opção inválida ou um argumento faltando. Isso é um fato sobre os builtins do bash. Não é conselho sobre o que o seu script deveria devolver, e nada obriga outro programa a seguir.

E aí tem o 1, o código de saída mais tabelado da internet, legendado em todo lugar como erro geral. Nenhum documento o define. POSIX e o manual do Bash dizem apenas que um valor diferente de zero indica falha. Contando os 256 valores possíveis, algum documento diz alguma coisa sobre 50 deles; os outros 206 ficam inteiramente a critério do programa.

Duas coisas que as tabelas erram

A primeira é o sysexits. Os códigos de 64 a 78 são apresentados em todo lugar como os códigos de saída padrão, e nunca fizeram parte do POSIX. Vêm de um cabeçalho em C escrito para o sendmail, e o cabeçalho é notavelmente franco consigo mesmo: diz que os valores existem apenas por compatibilidade de interface e estão obsoletos para o software base do FreeBSD, que foram escritos para o sendmail em particular e — logo antes de listá-los — que o significado dos códigos é aproximadamente o seguinte. Um conjunto de constantes cujo próprio autor chama os significados de aproximados é uma convenção razoável dentro de um projeto que já a usa, e uma aposta ruim se você espera que o programa de um desconhecido a respeite.

A segunda é que 128 mais um número de sinal nem sempre identifica um sinal. Para voltar do código ao sinal é preciso saber qual sinal carrega aquele número, e os números de sinal não são iguais em toda parte. No Linux sobre x86 o sinal 10 é SIGUSR1; em Alpha, SPARC e macOS é SIGBUS. Então o código 138 significa um sinal de usuário numa máquina e um erro de barramento em outra, e nenhuma tabela que imprima um único nome pode estar certa nas duas. Digite 138 acima e a ferramenta mostra a divisão em vez de escolher por você.

Há uma armadilha menor no sentido contrário. O código tem oito bits, então devolver algo maior dá a volta em silêncio: exit 256 chega como 0, o que transforma uma falha em sucesso. Medido aqui, exit 300 voltou como 44 e exit 257 como 1. Negativos são piores do que só transbordar: o bash converteu -1 em 255, enquanto o dash recusou com uma mensagem de número ilegal e devolveu 2, de modo que o mesmo script relata duas falhas diferentes conforme o shell que rodou.

Por que diferente de zero não quer dizer quebrado

A convenção que todo mundo carrega é que zero está bem e qualquer outra coisa é problema. As duas utilidades que mais aparecem num pipeline contradizem isso. O grep devolve 1 quando simplesmente não achou nada, e reserva o 2 para um erro de verdade. O diff devolve 1 quando os arquivos diferem, que é a resposta normal à pergunta que você fez, e também reserva o 2. O cmp faz o mesmo.

Essa é a razão prática de importar o aviso que aparece no fim de cada resultado desta página. Um script com set -e vai parar num grep que não achou nada, porque o shell não distingue entre uma resposta negativa e uma falha: as duas são 1. Saber quais das suas ferramentas usam o 1 como resposta e não como erro é mais útil que qualquer tabela de códigos padrão, porque é o caso que realmente morde.

Se você está escolhendo códigos para o seu próprio programa: zero para sucesso, diferente de zero para falha, e documente o que cada número significa. Esse é todo o contrato portável. Se quiser mais estrutura, escolha um esquema e escreva, porque quem for ler o seu código de saída não tem como consultar.

Por que é grátis?

Isto é uma tabela de consulta e um pouco de aritmética, rodando no seu navegador. Não há nada para rodar num servidor, então não há o que cobrar nem conta a criar.

Nada do que você digita é enviado, guardado ou registrado — e nem haveria muito a registrar: a entrada é um número entre 0 e 255.