Codes de sortie : un contrat entre les scripts et l'agent qui les appelle

Ce que c'est

Le manuel de GNU Bash indique qu'une commande tuée par le signal fatal N reçoit le code de sortie 128+N. Cette convention très répandue veut qu'un code supérieur à 128 signifie « tué par le signal N » (143 pour SIGTERM, 137 pour SIGKILL). POSIX exige seulement une valeur supérieure à 128 ; bash, dash et zsh utilisent 128+N, tandis que ksh93 renvoie 256+N. En revanche, POSIX impose 126 pour « trouvée mais non exécutable » et 127 pour « commande introuvable ». 0 signifie partout le succès ; les valeurs de 1 à 125 sont laissées au script, qui les définit comme il l'entend. Les codes de sortie tiennent sur 8 bits : exit 256 est reçu comme 0 et exit 300 comme 44.

Pourquoi c'est important

Un agent qui se contente de vérifier « zéro ou non » perd une information que le script, s'il est bien conçu, a déjà calculée pour lui. Un agent qui suppose qu'un code non nul précis a la même signification dans tous les outils finira par se tromper, car les valeurs 1 à 125 ne sont pas normalisées au-delà de « échec ». Deux autres pièges masquent le vrai code de sortie à l'appelant :

• Les pipelines : en bash, cmd1 | cmd2 ne renvoie normalement que le code de sortie de cmd2. set -o pipefail (bash, zsh, ksh ; absent de dash 0.5.12) modifie ce comportement : le code du pipeline est alors le code non nul le plus à droite parmi toutes les étapes. Sans cette option, une première étape en échec qui alimente un grep réussi donne l'apparence d'un succès complet. Le tableau PIPESTATUS de Bash, documenté dans la section Bash Variables du manuel, contient le code de sortie de chaque étape juste après l'exécution du pipeline (${PIPESTATUS[0]} pour la première commande) ; c'est le moyen de savoir quelle étape a échoué (zsh : pipestatus, en minuscules).
• Les deux signaux distincts de PowerShell : exit <n>, documenté dans about_Language_Keywords, renseigne $LASTEXITCODE et termine le script. throw, documenté dans about_Throw, lève une erreur bloquante (terminating error) ; si rien ne l'intercepte, pwsh -File et -Command se terminent tous deux avec le code 1 (about_Pwsh). Les pièges : un script dont le bloc catch absorbe l'erreur, ou qui n'émet que des erreurs non bloquantes, se termine avec 0 sous -File ; et sous -Command, tout code précis autre que 0 ou 1 est ramené à 1, sauf si la chaîne de commande se termine par exit $LASTEXITCODE.

Comment l'appliquer

• Réserver strictement 0 au succès dans chaque script généré par un agent, et documenter dans un commentaire en tête de fichier la signification de tout autre code défini par le script.
• Ajouter systématiquement set -o pipefail aux scripts bash dont le résultat dépend d'une étape antérieure d'un pipeline, et lire PIPESTATUS lorsque l'appelant doit savoir quelle étape a échoué.
• Terminer la gestion d'erreurs de plus haut niveau de tout script PowerShell par un exit 1 explicite (ou un code plus précis) dans le bloc catch, et pas seulement par un throw, chaque fois que le script doit signaler un échec à un appelant autre que PowerShell.
• Lorsqu'on encapsule un outil natif, vérifier $LASTEXITCODE (PowerShell) ou $? (shell POSIX) immédiatement après l'appel, avant qu'une autre commande ne l'écrase.

Pièges

• Considérer que le code de sortie 1 d'un outil inconnu a toujours le même sens que le code 1 d'un autre outil.
• Lire $? après une commande intermédiaire (même un simple echo), ou $LASTEXITCODE après l'exécution d'un autre programme natif.
• S'attendre à ce que le code de sortie d'un programme natif lancé dans un Start-Job ou un thread job parvienne au $LASTEXITCODE de l'appelant ; il faut le renvoyer comme sortie du job et vérifier le State du job.