Tema: exit-codes
-
Códigos de salida de docker/podman run: 125, 126, 127 y los códigos de señal que se transmiten a través de ellos
docker run reserva 125, 126 y 127 para fallos del propio Docker, un comando que no se puede invocar y un comando no encontrado, respectivamente; cualquier otro código se transmite sin cambios desde el proceso del contenedor, incluidos los códigos 128+señal (137 para SIGKILL, a menudo por OOM; 139 para SIGSEGV; 143 para SIGTERM). Para confirmar una terminación por falta de memoria, la forma documentada es el indicador OOMKilled del contenedor, no el 137 por sí solo, aunque en algunos hosts con cgroup v2 devuelve false incluso tras una terminación por OOM del kernel.
-
Códigos de salida de find y xargs: el 0/>0 básico de find frente a la escala 123-127 de xargs
find solo garantiza 0 si todo salió bien y un valor mayor que 0 si hubo errores, sin más detalle a propósito. xargs, en cambio, define una escala concreta de cómo falló el comando invocado: 123 para una salida distinta de cero ordinaria, 124 para la salida 255, 125 si lo mató una señal, 126 si no se puede ejecutar y 127 si no se encuentra. Al canalizar find hacia xargs hay que comprobar dos filosofías distintas de códigos de salida en un mismo pipeline.
-
grep, diff, cmp y test/[: el código de salida 1 significa «no encontrado», no fallo
grep, diff, cmp y el builtin test/[ usan la misma escala de tres valores: 0 para un resultado positivo, 1 para un resultado negativo que no es un error y 2 (o >1) para un problema real. Interpretar el 1 como un fallo del script es la interpretación errónea más habitual que comete un agente con estas herramientas.
-
Códigos de salida de curl: cómo distinguir un fallo de DNS, un fallo de TLS y --fail
curl devuelve un código numérico distinto para cada clase de fallo de transporte (resolución de nombres, conexión, TLS, timeout) y un código aparte, el 22, que solo aparece cuando se usa --fail o --fail-with-body ante estados de error HTTP. Un agente que evalúa el código de salida de curl en lugar de su texto puede decidir bien los reintentos sin analizar la salida.
-
timeout, kill y la convención 128+señal: deducir qué mató a un proceso a partir de su código de salida
GNU timeout usa 124 cuando vence el plazo, 125 ante un fallo interno propio, 126/127 si el comando no se puede invocar o no existe, y 137 si debe escalar a SIGKILL; kill -0 comprueba si un proceso existe sin enviar ninguna señal real; y la convención 128+número de señal (137 = SIGKILL, 139 = SIGSEGV, 143 = SIGTERM en x86/ARM) permite a un agente leer la causa concreta en un simple código de salida.
-
Códigos de salida de apt-get, dpkg, dnf y zypper: cuándo 100 significa actualizaciones y no un fallo
apt-get usa una división simple: 0 es éxito y 100 es error. dpkg distingue una comprobación fallida (1) de un error fatal de uso o del sistema (2). El check-update de dnf reutiliza 100 para indicar que SÍ hay actualizaciones disponibles, no un error. zypper define todo un rango, 100-107, de códigos informativos (no de error), por ejemplo para un reinicio pendiente, aunque 104 (paquete no encontrado) y 105 (interrumpido) significan que la acción no se realizó. Leer cualquiera de ellos como un simple booleano de éxito o fallo hace perder información real.
-
Códigos de salida de ssh y scp: 255 es un fallo del propio ssh; cualquier otro valor es del comando remoto
ssh devuelve el código de salida del comando remoto que ejecutó y reserva el 255 para fallos del propio ssh (conexión rechazada, fallo de autenticación, host key no coincidente) y para comandos remotos terminados por una señal. scp solo documenta la distinción entre 0 (éxito) y distinto de cero (fallo), así que para separar un problema de transporte local de un error remoto hay que recurrir al texto de stderr de ssh, no al código de scp.
-
Códigos de salida de Windows más allá de éxito/fallo: la máscara de bits de robocopy, los códigos del instalador de msiexec y $LASTEXITCODE
robocopy codifica varios hechos independientes (archivos copiados, archivos extra, discrepancias, fallos) en un único número inferior a 8 que debe leerse como máscara de bits, no compararse con cero; msiexec devuelve códigos específicos de Windows Installer, donde 3010 y 1641 significan éxito con reinicio pendiente, no fallo; y $LASTEXITCODE de PowerShell es la única forma fiable de ver el código real de un programa nativo, con reglas distintas según cómo se invocó el script.
-
Códigos de salida de wget y rsync: los códigos 23 y 24 de rsync no suelen ser el fallo que parecen
wget asigna un código fijo y pequeño a cada clase de error (red, SSL, autenticación, protocolo); la tabla de rsync es más amplia e incluye el 23 (transferencia parcial por error) y el 24 (transferencia parcial por archivos de origen desaparecidos), que habitualmente solo indica que un archivo desapareció durante el análisis y no demuestra que la transferencia esté rota.
-
Códigos de salida de git en los que un agente puede confiar: diff --exit-code, ls-remote --exit-code y el 125 de bisect run
La mayoría de los comandos porcelain de git solo documentan «distinto de cero en caso de error», sin una tabla numérica fija, pero tres comandos publican un contrato exacto y citable: git diff/--quiet usa 1 para indicar diferencias, git ls-remote --exit-code usa 2 cuando no hay refs coincidentes, y git bisect run reserva el 125 para «omitir esta revisión», no para «mala». Un merge con conflictos se señala mediante el estado (MERGE_HEAD), no con un número documentado.
-
make, ping y nc: códigos de salida que, sin avisar, no comprueban lo que se suele suponer
El código de salida 1 de GNU make con -q significa «un objetivo necesita reconstruirse», no un fallo. En ping, el 1 indica que no llegó ninguna respuesta (host caído, no una invocación errónea) y el 2, un error real de uso o de otro tipo. openssl s_client documenta que, por defecto, una conexión termina con éxito (código 0) aunque falle la verificación del certificado, salvo que se use -verify_return_error.
-
Códigos de salida de systemctl: is-active, is-enabled, is-failed y qué significa el código LSB 3
Los subcomandos is-active, is-enabled e is-failed de systemctl documentan un contrato simple de 0 frente a distinto de cero (en la práctica devuelven valores de estilo LSB, como 3 para inactivo y 4 para unidad desconocida), mientras que systemctl status sigue la convención antigua de los scripts init LSB, donde 3 significa «no se está ejecutando» y no un error de ejecución. Interpretar un 3 o un 4 como una invocación fallida es la forma más habitual en que los agentes malinterpretan systemctl.
-
Códigos de salida como contrato entre los scripts y el agente que los invoca
Un agente que ejecuta un script y continúa según su código de salida necesita que ese código signifique lo que dicen las convenciones del shell: 0 para éxito, números positivos pequeños para los fallos que define el propio script, 126/127 para un comando que no pudo ejecutarse y 128+n para la terminación por señal; además necesita pipefail o PIPESTATUS para ver el código real a través de una tubería.
Legible por máquina: JSON