Compreendendo Códigos de Saída: Tratamento Eficaz de Erros com $? e exit

No mundo da automação e dos scripts de shell, saber por que um script falhou é tão importante quanto saber que ele falhou. Os scripts Bash dependem fortemente de um mecanismo padronizado para relatar sucesso ou falha: códigos de saída, também conhecidos como status de saída ou códigos de retorno. Compreender como esses códigos funcionam, como inspecioná-los usando a variável especial $? e como encerrar scripts intencionalmente usando o comando exit é fundamental para escrever automação robusta, confiável e depurável.

Este guia detalhará os conceitos de códigos de saída, demonstrará como o Bash os rastreia automaticamente e mostrará técnicas práticas para implementar a verificação eficaz de erros em seus scripts de shell. Dominar isso garante que seus pipelines de automação falhem graciosamente e forneçam feedback significativo.

O Conceito de Status de Saída

Todo comando ou programa executado em um ambiente de shell do tipo Unix — seja um comando interno como cd, uma utilidade externa como grep, ou outro script de shell — retorna um valor inteiro ao ser concluído. Esse inteiro é o código de saída, que sinaliza o resultado da operação para o processo que o chamou.

A Convenção Padrão

A convenção para códigos de saída é universalmente reconhecida:

• 0 (Zero): Significa sucesso. O comando foi executado exatamente como esperado e nenhum erro ocorreu.
• 1 a 255: Significam falha ou condições de erro específicas. Esses valores diferentes de zero indicam que algo deu errado. Números mais altos geralmente correspondem a tipos específicos de erros (por exemplo, arquivo não encontrado, permissão negada, erro de sintaxe), embora o significado exato dependa do programa específico.

Nota sobre o Intervalo: Embora os códigos de saída sejam tecnicamente um valor de 8 bits (0-255), os scripts de shell geralmente se preocupam apenas com 0 para sucesso e com valores diferentes de zero para falha. Códigos de saída maiores que 255 são geralmente truncados ou interpretados como módulo 256 pelo shell.

Inspecionando o Último Código de Saída: A Variável $?

A variável especial do shell $? (dólar ponto de interrogação) é central para monitorar o status do comando. Imediatamente após a execução de qualquer comando, o shell armazena seu código de saída em $?.

Como Usar $?

Você deve verificar $? imediatamente após o comando de seu interesse, pois qualquer comando subsequente (até mesmo exibir a variável) substituirá seu valor.

Exemplo 1: Verificando Sucesso e Falha

# 1. Um comando bem-sucedido
echo "Teste de sucesso" > /dev/null
echo "Código de saída para sucesso: $?"

# 2. Um comando falhando (por exemplo, tentando listar um arquivo inexistente)
ls /caminho/inexistente
echo "Código de saída para falha: $?"

Saída Esperada:

Código de saída para sucesso: 0
ls: cannot access '/caminho/inexistente': No such file or directory
Código de saída para falha: 2

Implementando Verificação Condicional de Erros

Simplesmente saber o código de saída não é suficiente; o poder vem do uso dessa informação para controlar o fluxo do script. Isso é tipicamente feito usando instruções if ou operadores de curto-circuito (&& e ||).

Usando Instruções if

Esta é a maneira mais explícita de lidar com erros:

if grep -q "dados importantes" arquivo_log.txt;
then
    echo "Dados encontrados com sucesso."
else
    ULTIMO_STATUS=$?
    echo "Erro: Grep falhou com status $ULTIMO_STATUS. Dados não encontrados."
    # Considere sair aqui se o script não puder continuar
fi

No exemplo acima, grep -q suprime a saída (-q) e retorna 0 apenas se uma correspondência for encontrada. A estrutura if verifica o status de saída automaticamente, mas capturar explicitamente $? dentro do bloco else é útil para registro detalhado.

Usando Lógica de Curto-Circuito (&& e ||)

Para verificações sequenciais simples, os operadores de curto-circuito fornecem tratamento conciso de erros:

• && (E): O comando após && só é executado se o comando precedente teve sucesso (retornou 0).
• || (OU): O comando após || só é executado se o comando precedente falhou (retornou um valor diferente de zero).

Exemplo 2: Tratamento Conciso de Erros

# 1. Execute 'processar_dados' SOMENTE SE 'buscar_dados' for bem-sucedido
buscar_dados.sh && ./processar_dados.sh

# 2. Execute 'enviar_alerta' SOMENTE SE a operação principal falhar
rsync -a source/ dest/ || echo "RSync falhou em $(date)" >> /var/log/erros_rsync.log

Controlando a Terminação do Script com exit

O comando exit é usado para encerrar imediatamente o script de shell ou função atual e retornar um status de saída especificado para o chamador (que pode ser outro script ou o terminal do usuário).

Sintaxe e Uso

A sintaxe é simplesmente exit [código_status].

Se nenhum status for fornecido, exit usa como padrão o status do comando de primeiro plano executado mais recentemente. Se você chamar explicitamente exit 0 sem executar nenhum comando primeiro, ele retorna 0.

Exemplo 3: Saindo em Falha de Pré-Condição

Este script garante que um arquivo de configuração necessário exista antes de prosseguir.

ARQUIVO_CONFIG="/etc/app/config.conf"

if [[ ! -f "$ARQUIVO_CONFIG" ]]; then
    echo "Erro: Arquivo de configuração não encontrado em $ARQUIVO_CONFIG."
    # Termina o script imediatamente com um código de erro específico (por exemplo, 20)
    exit 20 
fi

echo "Configuração carregada. Continuando script..."
# ... resto do script
exit 0

Melhor Prática: Usando Códigos de Saída Significativos

Embora 0 e 1 cubram a maioria dos casos básicos, usar códigos diferentes de zero ajuda o script chamador a diagnosticar o problema exato:

| Código | Significado (Exemplo) |
| :--- |
| 0 | Sucesso |
| 1 | Erro genérico geral |
| 2-10 | Erros de sintaxe, problemas de análise de argumentos |
| 20 | Pré-requisito ausente (por exemplo, arquivo não encontrado) |
| 30 | Problema de permissão |

Fazendo Scripts Falharem Rapidamente: O Comando set

Para máxima confiabilidade em scripts complexos, é uma forte melhor prática habilitar a verificação de erros globalmente usando as opções do comando set no topo de seu script:

#!/bin/bash

# Sai imediatamente se um comando sair com um status diferente de zero.
set -e

# Trata variáveis não definidas como um erro ao substituir.
set -u

# Pipefail: Garante que o status de retorno de um pipeline seja o status do último comando que saiu com um status diferente de zero.
set -o pipefail

# (Opcional, mas útil) Imprime os comandos à medida que são executados para depuração
# set -x 

# Se qualquer comando abaixo falhar, o script para imediatamente.
ls /caminho/valido && grep padrao arquivo.txt && ./proximo_passo.sh

# A linha a seguir SÓ será executada se todos os comandos precedentes tiverem sucesso.
echo "Todos os passos concluídos."

Quando set -e está ativo, a execução do script para automaticamente na primeira status de saída diferente de zero, impedindo que comandos subsequentes sejam executados com base em dados intermediários defeituosos.