Lyx – Exit-Codes

Der Exit-Code ist die einzige Information, die ein beendetes Programm seinem Aufrufer maschinenlesbar hinterlässt. Alles andere — Meldungen, Logs, Reports — muss gelesen werden; der Exit-Code lässt sich abfragen. Plattformübergreifend gilt eine einzige feste Regel:

0 heißt Erfolg. Alles andere heißt Fehler, Warnung oder anwendungsspezifischer Status.

Eine allgemeingültige Tabelle für Anwendungen gibt es nicht — nur Konventionen. Diese Seite beschreibt, wie Lyx den Exit-Code setzt, welche Konventionen gelten und wie man eigene Codes entwirft, ohne in die üblichen Fallen zu laufen.

→ Fehlerbehandlung · std.process · std.io · Compiler-Parameter

Jedes Lyx-Programm beginnt bei main. Deklariert man sie mit Rückgabetyp int64, ist ihr Rückgabewert der Exit-Code des Prozesses:

fn main(): int64 {
    return 0;        // Erfolg
}

$ ./programm
$ echo $?
0

Der Weg dahin: Der vom Compiler erzeugte _start-Stub ruft main auf, nimmt deren Rückgabewert und übergibt ihn unverändert an den exit_group-Syscall. Es gibt keine Laufzeitschicht dazwischen, die den Wert noch verändert — was main zurückgibt, geht direkt an den Kernel.

import std.io;

fn PruefeKonfiguration(pfad: pchar): void {
    if (!FileExists(pfad)) {
        PrintLn("Konfiguration nicht lesbar");
        exit(3);                  // beendet das Programm hier, kein return noetig
    }
}

std.io bietet dafür zusätzlich ExitProc(code) — ein reiner Namensalias für exit.

fn main(): void ist zulässig und ergibt immer Exit-Code 0. Wer einen anderen Code braucht, nimmt int64 oder exit().

fn main(): int64 ohne return im Rumpf wird dagegen abgewiesen — seit der Typprüfung von 1.0.14 meldet der Compiler Funktion ohne return, Rueckgabetyp verlangt einen Wert 'main'.

Unter Linux und macOS überträgt der Kernel nur die unteren 8 Bit des Werts. Größere Zahlen laufen still über:

fn main(): int64 { return 256; }   // -> Exit-Code 0  (!)

Nachgemessen mit lyxc 1.0.16F:

Auf Windows ist der Exit-Code ein 32-Bit-Wert und wird nicht gestutzt. Wer beide Zielplattformen bedient, hält sich trotzdem an den Unix-Bereich — sonst verhält sich dasselbe Programm je nach Ziel anders.

Die Codes ab 126 sind belegt: Ein eigenes exit(137) ist von einem OOM-Kill nicht mehr zu unterscheiden. Der Bereich 1–125 ist der einzige, der einem allein gehört.

Wo eine feinere Einteilung gebraucht wird, ist sysexits.h die verbreitetste Konvention (verpflichtend ist sie nirgends):

EX_TEMPFAIL ist der nützlichste Eintrag der Liste: Er beantwortet die Frage, die ein automatischer Aufrufer wirklich hat — noch einmal versuchen oder aufgeben? Mailserver werten ihn bis heute so aus.

• Der Exit-Code ist ein 32-Bit-DWORD, gelesen mit GetExitCodeProcess.
• 259 ist tabu: Der Wert bedeutet STILL_ACTIVE. Ein Prozess, der mit 259 endet, gilt für jede Überwachung als noch laufend.
• 3010 heißt bei Installern „Erfolg, Neustart erforderlich„; 9009 meldet cmd.exe für „Befehl nicht gefunden“.
• Große negative Codes in CI-Protokollen sind Abstürze, kein return: -1073741819 ist 0xC0000005, eine Access Violation.

1. Exit-Codes sind eine API. Sobald sie dokumentiert und in fremden Skripten verbaut sind, lassen sie sich nicht mehr ändern. Deshalb klein halten und früh festlegen.
2. Nur 1–125 verwenden. 126 und darüber ist unter Unix belegt, 259 unter Windows.
3. Grobe Klassen statt Fehler-Enzyklopädie. Der Exit-Code beantwortet: Was soll der Aufrufer tun? (Wiederholen? Konfiguration reparieren? Bug melden?) Das Warum gehört nach stderr.
4. Der interne Fehler bekommt einen eigenen Code. „Melde einen Bug„ ist eine andere Handlungsaufforderung als „deine Eingabe ist kaputt“. rustc macht das mit 101 vor.
5. Temporär von dauerhaft trennen, wenn Wiederholungen denkbar sind — sonst versucht es der Aufrufer entweder nie oder immer.
6. Keine Bitmasken. robocopy liefert 1 = kopiert, 2 = Extras, 4 = Unterschiede, und erst ab 8 ist es ein Fehler. Damit ist es mit der gesamten „≠ 0 = Fehler„-Welt inkompatibel und muss überall gesondert behandelt werden.
7. Nie eine Anzahl (siehe Abschnitt 2).

import std.io;

con EXIT_OK:        int64 := 0;
con EXIT_EINGABE:   int64 := 1;   // Datei fehlt oder ist unlesbar
con EXIT_FORMAT:    int64 := 2;   // Datei da, Inhalt unbrauchbar
con EXIT_TEMPORAER: int64 := 3;   // Netz/Dienst weg — Wiederholung sinnvoll
con EXIT_INTERN:    int64 := 70;  // Bug in diesem Programm

fn main(): int64 {
    var daten: int64 := LadeEingabe();
    if (daten == 0) {
        PrintLn("Eingabe nicht lesbar");     // das Warum nach stderr/stdout
        return EXIT_EINGABE;                 // das Was-tun als Exit-Code
    }
    return EXIT_OK;
}

std.process liefert den Exit-Code eines Kindprozesses bereits ausgepackt — die Unit wendet WEXITSTATUS an, man bekommt also direkt die 0–255 und nicht den rohen wait-Status:

import std.io;
import std.process;

fn main(): int64 {
    var code: int64 := shell("exit 42"c);
    PrintLn(IntToStr(code));        // 42
    return 0;
}

Schlägt execve in einem mit spawn gestarteten Kind fehl, beendet sich das Kind mit 127 — dieselbe Konvention wie die Shell für „Kommando nicht gefunden“.

Der Compiler selbst benutzt (Stand 1.0.16F, nachgemessen):

Syntax- und Semantikfehler werden bewusst nicht über verschiedene Codes getrennt: Kein Aufrufer handelt darauf unterschiedlich, der Unterschied gehört in die Fehlermeldung. Warnungen ergeben 0.

Für ein Build-Skript heißt das:

lyxc main.lyx -o main
case $? in
  0) echo "gebaut" ;;
  1) echo "Quellcode fehlerhaft"; exit 1 ;;
  2) echo "Aufruf falsch — lyxc --help"; exit 2 ;;
esac

• $? gilt nur für das zuletzt ausgeführte Kommando. Wer ihn zweimal braucht, sichert ihn sofort in einer Variablen.
• Der Status einer Pipeline ist der des letzten Glieds: lyxc x.lyx | tee log meldet Erfolg, auch wenn lyxc scheitert. Gegenmittel: set -o pipefail oder ${PIPESTATUS[@]}.
• set -e hat so viele Ausnahmen (Bedingungen, &&/||-Ketten, Subshells), dass es kein Sicherheitsnetz ist.
• ssh benutzt 255 für eigene Verbindungsfehler und reicht sonst den entfernten Status durch — ein Programm, das selbst mit 255 endet, ist über ssh nicht mehr von einem Verbindungsabbruch zu unterscheiden.
• In Docker und Kubernetes heißt 137 fast immer OOM-Kill und 143 regulärer Shutdown per SIGTERM. Beides sind keine Anwendungsfehler — vor dem Debuggen den OOMKilled-Status prüfen.
• In cmd.exe bedeutet IF ERRORLEVEL 5 größer oder gleich 5. Genau prüfen mit IF %ERRORLEVEL% EQU 5.
• In PowerShell ist $? ein Wahrheitswert des letzten PowerShell-Ausdrucks; der Exit-Code eines nativen Programms steht in $LASTEXITCODE.

Geprüft mit lyxc 1.0.16F.

Letzte Aktualisierung: 2026-08-11