pcntl_wifstopped — Funktion · PHP-Referenz

Signatur

pcntl_wifstopped(int $status): bool

Beschreibung

pcntl_wifstopped() wertet den Statuswert aus, den pcntl_waitpid() oder pcntl_wait() per Referenzparameter liefert, und gibt true zurück, wenn der überwachte Kindprozess durch ein Signal gestoppt wurde – typischerweise durch SIGSTOP oder SIGTSTP. Ein gestoppter Prozess ist nicht beendet, sondern pausiert und kann mit SIGCONT fortgesetzt werden.

Die Funktion ist nützlich in Prozessmanagern, Task-Controllern oder Test-Frameworks, die Kindprozesse gezielt anhalten und weiterlaufen lassen müssen. Sie erlaubt es, zwischen einem gestoppten und einem beendeten Prozess zu unterscheiden, da beide Zustände über denselben Statusparameter übermittelt werden.

Wichtig: Damit pcntl_waitpid() auch gestoppte Kindprozesse meldet (und nicht nur beendete), muss das Flag WUNTRACED beim Aufruf gesetzt sein. Ohne dieses Flag liefert pcntl_wifstopped() immer false.

Diese Funktion steht nur auf POSIX-konformen Systemen (Linux, macOS) zur Verfügung und ist im CLI-SAPI am sinnvollsten einsetzbar. Auf Windows ist die PCNTL-Extension nicht verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$status Pflicht	int		Der Statuswert, den `pcntl_waitpid()` oder `pcntl_wait()` per Referenzparameter befüllt hat. Dieser Rohwert kodiert den Zustand des Kindprozesses und darf nicht manuell konstruiert werden.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Kindprozess durch ein Signal gestoppt wurde; andernfalls false. Wurde pcntl_waitpid() ohne das Flag WUNTRACED aufgerufen, ist der Rückgabewert stets false.

Beispiele

Kindprozess stoppen und Status prüfen

<?php
$pid = pcntl_fork();

if ($pid === -1) {
    die('Fork fehlgeschlagen');
} elseif ($pid === 0) {
    // Kindprozess: läuft in einer Schleife
    while (true) {
        sleep(1);
    }
    exit(0);
} else {
    // Elternprozess: kurz warten, dann Kind stoppen
    sleep(1);
    posix_kill($pid, SIGSTOP); // Kind anhalten

    // WUNTRACED: waitpid meldet auch gestoppte Prozesse
    $exitedPid = pcntl_waitpid($pid, $status, WUNTRACED);

    if (pcntl_wifstopped($status)) {
        $signal = pcntl_wstopsig($status);
        echo "Kindprozess {$exitedPid} wurde durch Signal {$signal} gestoppt.\n";

        // Kindprozess fortsetzen und dann beenden
        posix_kill($pid, SIGCONT);
        posix_kill($pid, SIGTERM);
        pcntl_waitpid($pid, $status2);
        echo "Kindprozess beendet.\n";
    } else {
        echo "Kindprozess ist nicht gestoppt.\n";
    }
}

Kindprozess 12345 wurde durch Signal 19 gestoppt. Kindprozess beendet.

Zustandsunterscheidung: gestoppt vs. beendet

<?php
function checkChildStatus(int $pid, int $status): void
{
    if (pcntl_wifstopped($status)) {
        $sig = pcntl_wstopsig($status);
        echo "PID {$pid}: Gestoppt durch Signal {$sig}\n";
    } elseif (pcntl_wifsignaled($status)) {
        $sig = pcntl_wtermsig($status);
        echo "PID {$pid}: Durch Signal {$sig} beendet\n";
    } elseif (pcntl_wifexited($status)) {
        $code = pcntl_wexitstatus($status);
        echo "PID {$pid}: Normal beendet mit Exit-Code {$code}\n";
    } else {
        echo "PID {$pid}: Unbekannter Status\n";
    }
}

$pid = pcntl_fork();
if ($pid === 0) {
    sleep(10);
    exit(0);
} else {
    sleep(1);
    posix_kill($pid, SIGSTOP);
    pcntl_waitpid($pid, $status, WUNTRACED);
    checkChildStatus($pid, $status);

    posix_kill($pid, SIGKILL);
    pcntl_waitpid($pid, $status2);
    checkChildStatus($pid, $status2);
}

PID 12346: Gestoppt durch Signal 19 PID 12346: Durch Signal 9 beendet

// Wichtig · Fallstricke

Flag WUNTRACED erforderlich: Ohne das Flag WUNTRACED bei pcntl_waitpid() werden gestoppte Kindprozesse nicht gemeldet und pcntl_wifstopped() gibt immer false zurück.

Nur POSIX-Systeme: Die gesamte PCNTL-Extension ist auf Windows nicht verfügbar. Code, der diese Funktion nutzt, ist nicht portabel auf Windows-Server.

Nur im CLI-SAPI empfohlen: Die Verwendung von pcntl_*-Funktionen in einem Webserver-Kontext (z. B. FPM, Apache-Modul) kann zu unvorhersehbarem Verhalten führen und sollte vermieden werden.

Den Signal-Wert des Stop-Signals kann man mit pcntl_wstopsig() auslesen, wenn pcntl_wifstopped() true zurückgegeben hat.

Siehe auch

pcntl_waitpid pcntl_wait pcntl_wifexited pcntl_wifsignaled pcntl_wstopsig pcntl_wtermsig pcntl_wexitstatus pcntl_fork posix_kill