proc_get_status — Funktion · PHP-Referenz

Signatur

proc_get_status(resource $process): array|false

Beschreibung

proc_get_status() gibt detaillierte Laufzeitinformationen zu einem Prozess zurück, der zuvor mit proc_open() gestartet wurde. Das zurückgegebene Array enthält unter anderem die Prozess-ID (PID), den Befehl, den Ausführungsstatus sowie Exit-Code und Signalstatus.

Die Funktion ist besonders nützlich, wenn geprüft werden soll, ob ein Hintergrundprozess noch läuft, oder um nach dem Beenden des Prozesses seinen Exit-Code auszulesen. Da proc_close() den Exit-Code nur korrekt liefert, wenn der Prozess ordnungsgemäß beendet wurde, empfiehlt es sich, vor dem Schließen proc_get_status() zu verwenden, um den Exit-Code zu sichern.

Ein wichtiger Hinweis: Der Exit-Code (exitcode) im zurückgegebenen Array enthält nur dann einen sinnvollen Wert, wenn der Prozess bereits beendet ist (running === false). Wird die Funktion aufgerufen, während der Prozess noch läuft, ist der Wert -1. Außerdem wird der Exit-Code nur beim ersten Aufruf nach Prozessende korrekt geliefert – spätere Aufrufe können -1 zurückgeben.

Die Funktion eignet sich für alle Szenarien, in denen externe Prozesse überwacht und gesteuert werden müssen, etwa beim Ausführen von Shell-Kommandos, Parallelverarbeitung oder der Kommunikation mit externen Diensten über Pipes.

Parameter

Name	Typ	Default	Beschreibung
$process Pflicht	resource		Die Prozess-Ressource, die von `proc_open()` zurückgegeben wurde.

Rückgabewert

Typ

array|false

Beschreibung

Gibt bei Erfolg ein assoziatives Array zurück, bei Fehler false. Das Array enthält folgende Schlüssel:

command (string) – Der gestartete Befehl.
pid (int) – Prozess-ID des Kindprozesses.
running (bool) – true, wenn der Prozess noch läuft, sonst false.
signaled (bool) – true, wenn der Prozess durch ein Signal beendet wurde (nur Unix).
stopped (bool) – true, wenn der Prozess durch ein Signal gestoppt wurde (nur Unix).
exitcode (int) – Exit-Code des Prozesses; -1 wenn noch laufend oder nicht verfügbar.
termsig (int) – Signal, das den Prozess beendet hat (nur wenn signaled === true).
stopsig (int) – Signal, das den Prozess gestoppt hat (nur wenn stopped === true).

Beispiele

Prozess starten und auf Beendigung warten

<?php
$descriptorspec = [
    0 => ['pipe', 'r'],  // stdin
    1 => ['pipe', 'w'],  // stdout
    2 => ['pipe', 'w'],  // stderr
];

$process = proc_open('sleep 2 && echo Fertig', $descriptorspec, $pipes);

if (is_resource($process)) {
    // Warten bis der Prozess beendet ist
    do {
        usleep(100000); // 100ms warten
        $status = proc_get_status($process);
    } while ($status['running']);

    $exitCode = $status['exitcode'];
    echo "Prozess beendet mit Exit-Code: $exitCode" . PHP_EOL;

    $output = stream_get_contents($pipes[1]);
    echo "Ausgabe: $output";

    foreach ($pipes as $pipe) {
        fclose($pipe);
    }
    proc_close($process);
}

Prozess beendet mit Exit-Code: 0 Ausgabe: Fertig

Exit-Code sicher vor proc_close() sichern

<?php
$descriptorspec = [
    1 => ['pipe', 'w'],
    2 => ['pipe', 'w'],
];

$process = proc_open('ls /nicht-vorhanden', $descriptorspec, $pipes);

if (is_resource($process)) {
    // Alle Ausgaben lesen, damit der Prozess nicht blockiert
    $stdout = stream_get_contents($pipes[1]);
    $stderr = stream_get_contents($pipes[2]);
    fclose($pipes[1]);
    fclose($pipes[2]);

    // Exit-Code VOR proc_close() sichern
    $status = proc_get_status($process);
    $exitCode = $status['exitcode'];

    proc_close($process);

    echo "Exit-Code: $exitCode" . PHP_EOL;
    if ($stderr) {
        echo "Fehler: $stderr";
    }
}

Exit-Code: 2 Fehler: ls: cannot access '/nicht-vorhanden': No such file or directory

// Wichtig · Fallstricke

Exit-Code nur einmal verfügbar: Der korrekte Exit-Code steht nur beim ersten Aufruf von proc_get_status() nach Prozessende zur Verfügung. Bei weiteren Aufrufen kann der Wert -1 sein. Daher sollte der Exit-Code sofort nach Erkennung von running === false gespeichert werden.

Windows-Einschränkungen: Die Felder signaled, stopped, termsig und stopsig sind unter Windows immer false bzw. 0, da das Windows-Prozessmodell keine POSIX-Signale unterstützt.

Zombie-Prozesse: Wird proc_get_status() nie aufgerufen und der Prozess nie mit proc_close() geschlossen, kann ein Zombie-Prozess entstehen. Immer sicherstellen, dass proc_close() aufgerufen wird.

Siehe auch

proc_open proc_close proc_terminate proc_nice shell_exec exec