make, ping e nc: códigos de saída que, silenciosamente, não verificam o que você imagina

O que é

Três ferramentas que um agente costuma chamar via shell têm, cada uma, um código de saída cujo significado é fácil de supor de forma errada.

make: "GNU make exits with a status of zero if all makefiles were successfully parsed and no targets that were built failed. A status of one will be returned if the -q flag was used and make determines that a target needs to be rebuilt. A status of two will be returned if any errors were encountered." Sem -q, o código 1 não ocorre em builds comuns: uma falha comum de receita produz o código 2. O Error 1 da mensagem do make é o código da receita, não o do make.

ping: "If ping does not receive any reply packets at all it will exit with code 1 ... On other error it exits with code 2. Otherwise it exits with code 0." O código 1 significa que o ping funcionou corretamente e está informando "no answer" (sem resposta): um host fora do ar, um descarte por firewall ou um endereço errado que ainda assim é resolvido. O código 2 é reservado para quando o próprio ping falha (argumentos inválidos, nome não resolvido, problemas de permissão).

nc/ncat: as implementações variam, e muitas (incluindo o netcat do OpenBSD) não documentam uma tabela formal de códigos de saída. O Ncat, do Nmap, documenta: "The exit code reflects whether a connection was made and completed successfully. 0 means there was no error. 1 means there was a network error of some kind ... 2 is reserved for all other errors, like an invalid option or a nonexistent file." Considere não verificado o código de qualquer outra variante de nc, a menos que você consulte a documentação dela.

openssl s_client: a opção -verify documenta uma armadilha real: "Unless the -verify_return_error option is given, the verify operation continues after errors ... As a side effect the connection will never fail due to a server certificate verify failure." Sem essa opção, uma sessão TLS concluída termina com código 0 mesmo que o certificado seja inválido, expirado ou autoassinado.

Por que importa

Em cada caso, a verificação ingênua "0 é sucesso, qualquer outro valor é falha" leva a uma conclusão errada: o modo -q do make inverte o sentido habitual do 1; o código 1 do ping é uma observação legítima da rede, não uma chamada quebrada; e o código 0 padrão do openssl s_client pode significar "conectado a um atacante com um certificado inválido", e não "conexão verificada".

Como aplicar

• Com make -q, trate o código 1 como o sinal esperado de "precisa reconstruir" e reserve o tratamento de erros reais para o código 2.
• Use a distinção entre 1 e 2 do ping para separar "host inalcançável" (1, vale alertar sobre o alvo) de "o próprio ping falhou" (2, vale revisar seus argumentos).
• Prefira nc -z com os códigos documentados da sua implementação específica, ou verifique o texto da saída; não presuma que a semântica seja a mesma entre o nc do OpenBSD, o GNU netcat e o Ncat.
• Sempre adicione -verify_return_error e -verify_hostname <name> às chamadas de openssl s_client usadas em verificações automatizadas de certificado: sem a primeira opção, o código 0 não prova nada sobre o certificado, e sem a segunda, um certificado válido emitido para outro nome ainda assim termina com código 0.

Armadilhas

• Escrever em um script make -q; [ $? -eq 0 ] || echo "build broken": um código de saída 1 com -q significa o oposto de quebrado.
• Confiar em um simples openssl s_client ... ; echo $? como verificação de validação de certificado.