Exit-Codes als Vertrag zwischen Skripten und dem aufrufenden Agenten

Worum es geht

Laut GNU-Bash-Handbuch erhält ein Befehl, der durch das fatale Signal N beendet wird, den Exit-Status 128+N. Das ist die weit verbreitete Konvention, dass Codes über 128 bedeuten: «durch Signal N beendet» (143 für SIGTERM, 137 für SIGKILL). POSIX selbst verlangt lediglich einen Wert über 128; bash, dash und zsh verwenden 128+N, ksh93 meldet dagegen 256+N. POSIX schreibt jedoch 126 für «gefunden, aber nicht ausführbar» und 127 für «Befehl nicht gefunden» vor. 0 bedeutet überall Erfolg; 1–125 stehen dem Skript zur freien Definition zur Verfügung. Exit-Codes sind 8 Bit breit: exit 256 kommt als 0 an, exit 300 als 44.

Warum es wichtig ist

Ein Agent, der nur prüft, ob der Code null ist oder nicht, verliert Informationen, die ein sauberes Skript bereits für ihn ermittelt hat. Ein Agent, der annimmt, dass eine bestimmte Zahl ungleich null bei allen Tools dasselbe bedeutet, liegt früher oder später falsch, denn 1–125 sind über «nicht erfolgreich» hinaus nicht standardisiert. Zwei weitere Stolperfallen verbergen den tatsächlichen Exit-Code vor dem Aufrufer:

• Pipelines: cmd1 | cmd2 meldet in bash normalerweise nur den Exit-Status von cmd2. set -o pipefail (bash, zsh, ksh; nicht in dash 0.5.12) ändert das: Der Status der Pipeline ist dann der am weitesten rechts stehende Status ungleich null einer beliebigen Stufe. Ohne diese Option sieht eine fehlschlagende erste Stufe, die in ein erfolgreiches grep mündet, wie ein vollständiger Erfolg aus. Das im Bash-Handbuch im Abschnitt «Bash Variables» beschriebene Array PIPESTATUS enthält unmittelbar nach der Pipeline den Exit-Status jeder einzelnen Stufe (${PIPESTATUS[0]} für den ersten Befehl) und zeigt damit, welche Stufe fehlgeschlagen ist (zsh: kleingeschrieben pipestatus).
• Zwei verschiedene Signale in PowerShell: exit <n>, beschrieben in about_Language_Keywords, setzt $LASTEXITCODE und beendet das Skript. throw, beschrieben in about_Throw, löst einen terminierenden Fehler aus; wird er nicht abgefangen, enden pwsh -File und -Command beide mit Exit-Code 1 (about_Pwsh). Die Fallstricke: Ein Skript, dessen catch den Fehler verschluckt oder das nur nicht terminierende Fehler ausgibt, endet unter -File mit 0; und unter -Command wird jeder spezifische Code ausser 0/1 auf 1 reduziert, sofern der Befehlsstring nicht mit exit $LASTEXITCODE endet.

So wird es angewendet

• In jedem vom Agenten erzeugten Skript 0 strikt für Erfolg reservieren und die Bedeutung aller weiteren vom Skript definierten Codes in einem Kommentar am Anfang dokumentieren.
• Bash-Skripten, deren Ergebnis von einer früheren Stufe einer Pipeline abhängt, stets set -o pipefail hinzufügen und PIPESTATUS auslesen, wenn der Aufrufer wissen muss, welche Stufe fehlgeschlagen ist.
• Die Fehlerbehandlung auf oberster Ebene jedes PowerShell-Skripts im catch-Block mit einem expliziten exit 1 (oder einem spezifischeren Code) abschliessen, nicht nur mit throw, sobald das Skript einem Aufrufer ausserhalb von PowerShell einen Fehler melden muss.
• Beim Einbinden eines nativen Tools $LASTEXITCODE (PowerShell) bzw. $? (POSIX-Shell) unmittelbar nach dem Aufruf prüfen, bevor ein anderer Befehl den Wert überschreibt.

Stolpersteine

• Exit-Code 1 eines unbekannten Tools wird so behandelt, als bedeute er immer dasselbe wie Exit-Code 1 eines anderen Tools.
• $? wird nach einem dazwischenliegenden Befehl (auch nach echo) gelesen, oder $LASTEXITCODE nach dem Lauf eines weiteren nativen Programms.
• Es wird erwartet, dass ein nativer Exit-Code innerhalb eines Start-Job oder Thread-Jobs im $LASTEXITCODE des Aufrufers ankommt; stattdessen den Code als Job-Ausgabe zurückgeben und den State des Jobs prüfen.