pcntl_wstopsig — Funktion · PHP-Referenz

Signatur

pcntl_wstopsig(int $status): int

Beschreibung

pcntl_wstopsig() wertet den Status-Wert aus, den pcntl_wait() oder pcntl_waitpid() für einen Kind-Prozess liefert, und gibt die Nummer des Signals zurück, das diesen Kind-Prozess zum Anhalten (SIGSTOP, SIGTSTP usw.) gebracht hat.

Diese Funktion ist nur sinnvoll, wenn zuvor mit pcntl_wifstopped() geprüft wurde, dass der Kind-Prozess tatsächlich angehalten (und nicht beendet) wurde. Andernfalls ist der Rückgabewert undefiniert und nicht aussagekräftig.

Typische Anwendungsfälle sind Daemon- oder Job-Control-Implementierungen, bei denen der Eltern-Prozess überwacht, welche Signale seine Kind-Prozesse pausieren, um darauf geeignet reagieren zu können – etwa um den Kind-Prozess mit SIGCONT fortzusetzen oder entsprechende Log-Einträge zu schreiben.

Die PCNTL-Erweiterung steht nur auf Unix-artigen Systemen (Linux, macOS usw.) zur Verfügung und ist auf Windows nicht nutzbar. Der Status-Parameter ist der rohe Integer-Wert, den die Wait-Funktionen über ihren Referenz-Parameter zurückliefern.

Parameter

Name	Typ	Default	Beschreibung
$status Pflicht	int		Der Status-Integer-Wert, der von `pcntl_wait()` oder `pcntl_waitpid()` per Referenz-Parameter befüllt wurde. Dieser Wert enthält kodierte Informationen über den Zustand des Kind-Prozesses.

Rückgabewert

Typ

int

Beschreibung

Gibt die Signalnummer (z. B. SIGTSTP, SIGSTOP) zurück, welche den Kind-Prozess zum Anhalten veranlasst hat. Der Rückgabewert ist nur dann aussagekräftig, wenn pcntl_wifstopped() zuvor true zurückgegeben hat.

Beispiele

Kind-Prozess auf Stoppsignal überwachen

<?php
$pid = pcntl_fork();

if ($pid === -1) {
    die('Fork fehlgeschlagen');
} elseif ($pid === 0) {
    // Kind-Prozess: läuft und wartet auf Signale
    echo "Kind-Prozess PID: " . getmypid() . PHP_EOL;
    sleep(30);
    exit(0);
} else {
    // Eltern-Prozess: wartet auf Statusänderung des Kindes
    // WUNTRACED sorgt dafür, dass auch Stopps gemeldet werden
    $childPid = pcntl_waitpid($pid, $status, WUNTRACED);

    if (pcntl_wifstopped($status)) {
        $signal = pcntl_wstopsig($status);
        echo "Kind-Prozess {$childPid} wurde durch Signal {$signal} angehalten." . PHP_EOL;
        // Kind-Prozess wieder fortsetzen
        posix_kill($childPid, SIGCONT);
    } elseif (pcntl_wifexited($status)) {
        $code = pcntl_wexitstatus($status);
        echo "Kind-Prozess {$childPid} beendet mit Exit-Code {$code}." . PHP_EOL;
    }
}

Kind-Prozess PID: 12345 Kind-Prozess 12345 wurde durch Signal 20 angehalten.

Signalnummer mit Konstantenname ausgeben

<?php
// Hilfsfunktion: Signalnummer auf Name abbilden
function signalName(int $signo): string {
    $map = [
        SIGSTOP  => 'SIGSTOP',
        SIGTSTP  => 'SIGTSTP',
        SIGTTIN  => 'SIGTTIN',
        SIGTTOU  => 'SIGTTOU',
    ];
    return $map[$signo] ?? "Signal #{$signo}";
}

$pid = pcntl_fork();
if ($pid === -1) {
    die('Fork fehlgeschlagen');
} elseif ($pid === 0) {
    sleep(60);
    exit(0);
} else {
    // Sende SIGTSTP an das Kind, dann warte
    posix_kill($pid, SIGTSTP);
    pcntl_waitpid($pid, $status, WUNTRACED);

    if (pcntl_wifstopped($status)) {
        $sig = pcntl_wstopsig($status);
        echo "Kind angehalten durch: " . signalName($sig) . PHP_EOL;
    }

    // Kind wieder laufen lassen und auf Ende warten
    posix_kill($pid, SIGCONT);
    posix_kill($pid, SIGTERM);
    pcntl_waitpid($pid, $status);
    echo "Kind beendet." . PHP_EOL;
}

Kind angehalten durch: SIGTSTP Kind beendet.

// Wichtig · Fallstricke

Nur auf Unix-artigen Systemen verfügbar: Die PCNTL-Erweiterung funktioniert nicht unter Windows. Beim Einsatz in Web-SAPIs (Apache, PHP-FPM) ist Vorsicht geboten, da das Prozessmodell des Webservers durch pcntl_fork() gestört werden kann.

Reihenfolge der Prüfungen beachten: pcntl_wstopsig() liefert nur dann sinnvolle Werte, wenn pcntl_wifstopped($status) zuvor true zurückgegeben hat. Ohne diese Prüfung kann der Rückgabewert irreführend sein.

Damit gestoppte Kind-Prozesse gemeldet werden, muss pcntl_waitpid() mit dem Flag WUNTRACED aufgerufen werden, da sonst Stoppereignisse nicht an den Eltern-Prozess weitergegeben werden.

Siehe auch

pcntl_wait pcntl_waitpid pcntl_wifstopped pcntl_wifexited pcntl_wexitstatus pcntl_wtermsig pcntl_wifsignaled pcntl_fork