Comando timeout: Limitando o Tempo de Execução de Comandos

2026-06-05 Tempo de leitura: Cerca de 10 min Dificuldade: Iniciante

O Que Você Vai Aprender

• Como limitar quanto tempo um comando executa com timeout
• Como parar automaticamente um comando que "trava e nunca retorna"
• Como detectar um timeout usando o status de saída 124
• Como forçar o encerramento de um processo teimoso que ignora SIGTERM com -k

1. O Que é o Comando timeout?

Conclusão: timeout encerra automaticamente um comando quando ele excede o limite de tempo que você definiu. É a ferramenta ideal para prevenir travamentos.

timeout 10 command
        |   |
        |   o comando que voce quer executar
        limite de tempo (segundos)

2. Por Que Você Precisa do timeout?

Conclusão: Um comando que trava esperando rede ou em um loop infinito pode congelar todo seu script. timeout previne isso.

3. Uso Básico (Especificando o Tempo)

Conclusão: A forma é timeout DURACAO comando. Um número simples significa segundos; adicione s/m/h/d para unidades.

A forma mais básica é:

$ timeout 10 sleep 30

sleep 30 normalmente espera 30 segundos. Mas com timeout 10, ele é parado após 10 segundos.

Você pode anexar uma unidade (sufixo) à duração.

$ timeout 30s command    # 30 segundos
$ timeout 5m command     # 5 minutos
$ timeout 1h command     # 1 hora
$ timeout 2d command     # 2 dias

4. Detectando Timeouts com Status de Saída 124

Conclusão: Quando timeout interrompe um comando, o status de saída é 124. Se echo $? mostrar 124, houve timeout.

Quando timeout para um comando porque o tempo expirou, o status de saída se torna 124. Verificar isso permite detectar um timeout mecanicamente.

$ timeout 1 sleep 10
$ echo $?

124

Se terminar a tempo, o próprio status do comando é retornado.

$ timeout 10 sleep 1
$ echo $?

0

5. Forçando o Encerramento de Processos Teimosos com -k

Conclusão: timeout envia SIGTERM por padrão. Se isso for ignorado, use -k DURACAO para enviar SIGKILL após um período de graça e parar com certeza.

$ timeout -k 5 10 command

Isso significa:

• Primeiro, após 10 segundos, enviar SIGTERM (o pedido educado) ao comando
• Se ainda não parou após mais 5 segundos, enviar SIGKILL (kill forçado)

timeout -k 5 10 command
         |  |
         |  o limite real de tempo (10s) -> SIGTERM
         graca extra (5s) -> SIGKILL se ainda estiver executando

6. Especificando o Sinal (-s)

Conclusão: Use -s para alterar o sinal enviado. Se quiser que o status do próprio comando seja retornado no timeout, use --preserve-status.

Por padrão SIGTERM é enviado, mas você pode especificar um sinal diferente com -s (--signal).

$ timeout -s SIGINT 10 command

Isso envia SIGINT, o mesmo que Ctrl+C. Alguns comandos encerram mais graciosamente com isso do que com SIGTERM.

Quando você quer que o timeout não reescreva o status para 124, use --preserve-status.

$ timeout --preserve-status 10 command

7. Erros Comuns de Iniciantes

Conclusão: É fácil confundir a ordem de duração e comando, o significado de 124 e a ordem de argumentos do -k.

7-1. Invertendo a ordem de duração e comando

# NG: o comando vem primeiro
$ timeout sleep 30 10

# OK: duracao -> comando
$ timeout 10 sleep 30

7-2. Confundir 124 com um "erro"

7-3. Pensar que limitou todo o pipeline quando apenas parte foi limitada

# Isto nao limita todo o pipeline
$ timeout 10 grep pattern file | sort

Um pipe (|) passa o resultado do comando da esquerda para o comando da direita. Mesmo assim, apenas a parte timeout 10 grep pattern file é limitada; | sort é tratado separadamente.

Para envolver um pipeline inteiro de uma vez, use bash -c 'comandos', que faz o shellUm programa interativo que interpreta os comandos digitados e os executa. tratar a linha toda como um único comando.

$ timeout 10 bash -c 'grep pattern file | sort'

8. Mini Exercícios: Tente Você Mesmo

Conclusão: Três tarefas - cortar, verificar status de saída, kill forçado - para sentir o timeout na prática.

Exercício 1: Corte sleep 30 Após 3 Segundos

Tarefa: Faça um comando que normalmente leva 30 segundos terminar em 3.

$ timeout 3 sleep 30

Exercício 2: Confirme Que Houve Timeout

Tarefa: Logo após o Exercício 1, imprima o status de saída e confirme que é 124.

$ timeout 3 sleep 30
$ echo $?

Exercício 3: Encerre à Força Quando Não Parar

Tarefa: Escreva um comando que pare sleep 30 com "SIGTERM em 5 segundos, depois SIGKILL se ainda estiver executando 2 segundos depois."

$ timeout -k 2 5 sleep 30

9. Templates para Copiar e Colar

Conclusão: Tenha os padrões comuns à mão - básico, com unidades, detecção, kill forçado, pipeline.

# Basico: parar apos 10 segundos
timeout 10 command

# Adicionar unidade (segundos / minutos)
timeout 30s command
timeout 5m command

# Detectar timeout (124 significa timeout)
timeout 10 command
echo $?

# Kill forcado se nao parar (10s + 5s de graca, depois SIGKILL)
timeout -k 5 10 command

# Limitar um pipeline inteiro
timeout 10 bash -c 'commandA | commandB'

# Parar com SIGINT (como Ctrl+C)
timeout -s SIGINT 10 command

Resumo em Três Linhas

• timeout DURACAO comando limita quanto tempo um comando pode rodar. A ordem é duração primeiro, comando depois
• O status de saída 124 é o sinal de timeout, não um erro. Significa "cortado exatamente como planejado"
• Para um processo que ignora o SIGTERM, use duas etapas com -k GRACA LIMITE. O SIGKILL é o último recurso