sapi_windows_generate_ctrl_event — Funktion · PHP-Referenz

Signatur

sapi_windows_generate_ctrl_event(int $event, int $pid = 0): bool

Beschreibung

sapi_windows_generate_ctrl_event() ist eine Windows-spezifische Funktion, die ein CTRL-Signal an einen Prozess oder eine Prozessgruppe sendet. Sie ist das PHP-Äquivalent der Windows-API-Funktion GenerateConsoleCtrlEvent() und steht ausschließlich in der Windows-CLI-SAPI zur Verfügung.

Der Parameter $event gibt den Ereignistyp an: PHP_WINDOWS_EVENT_CTRL_C (entspricht CTRL+C) oder PHP_WINDOWS_EVENT_CTRL_BREAK (entspricht CTRL+BREAK). Der Parameter $pid gibt die Prozessgruppen-ID des Zielprozesses an; der Wert 0 sendet das Ereignis an alle Prozesse in der aktuellen Konsolen-Prozessgruppe.

Typischer Anwendungsfall ist das kooperative Beenden von Kindprozessen, die mit proc_open() oder popen() gestartet wurden und auf CTRL-Ereignisse reagieren. Viele Konsolenprogramme unter Windows (z. B. FFmpeg, Python-Skripte) behandeln CTRL+BREAK als sauberes Abbruchsignal und führen dann ordnungsgemäßes Aufräumen durch, bevor sie sich beenden.

Achtung: Die Funktion ist ausschließlich unter Windows verfügbar und nur in der CLI-SAPI nutzbar. Auf anderen Plattformen oder in anderen SAPIs existiert sie nicht; ein Aufruf würde zu einem fatalen Fehler führen. Vor dem Aufruf sollte mit function_exists() geprüft werden, ob die Funktion vorhanden ist.

Parameter

Name	Typ	Default	Beschreibung
$event Pflicht	int		Der Typ des CTRL-Ereignisses. Gültige Werte sind die Konstanten `PHP_WINDOWS_EVENT_CTRL_C` und `PHP_WINDOWS_EVENT_CTRL_BREAK`.
$pid	int	0	Die Prozessgruppen-ID des Zielprozesses. Der Wert `0` sendet das Ereignis an alle Prozesse der aktuellen Konsolen-Prozessgruppe. Wenn ein Kindprozess mit `proc_open()` gestartet wurde, kann dessen PID hier übergeben werden.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn das Ereignis erfolgreich gesendet wurde, andernfalls false. Ein Rückgabewert von true bedeutet nicht, dass der Zielprozess das Ereignis tatsächlich verarbeitet hat.

Beispiele

CTRL+BREAK an einen Kindprozess senden

<?php
if (!function_exists('sapi_windows_generate_ctrl_event')) {
    die('Diese Funktion ist nur unter Windows in der CLI-SAPI verfügbar.');
}

$descriptors = [
    0 => ['pipe', 'r'],
    1 => ['pipe', 'w'],
    2 => ['pipe', 'w'],
];

// Kindprozess starten (z. B. ein lang laufendes Skript)
$process = proc_open('ping -t 127.0.0.1', $descriptors, $pipes);

if (is_resource($process)) {
    $status = proc_get_status($process);
    $pid = $status['pid'];

    echo "Kindprozess gestartet mit PID: {$pid}\n";
    sleep(3); // 3 Sekunden warten

    // CTRL+BREAK-Ereignis senden, um den Prozess sauber zu beenden
    $result = sapi_windows_generate_ctrl_event(PHP_WINDOWS_EVENT_CTRL_BREAK, $pid);
    echo $result ? "CTRL+BREAK erfolgreich gesendet.\n" : "Fehler beim Senden des Ereignisses.\n";

    proc_close($process);
}

Kindprozess gestartet mit PID: 12345 CTRL+BREAK erfolgreich gesendet.

CTRL+C an die aktuelle Prozessgruppe senden

<?php
if (!function_exists('sapi_windows_generate_ctrl_event')) {
    die('Nur unter Windows in der CLI verfügbar.');
}

// CTRL+C an alle Prozesse der aktuellen Konsolen-Prozessgruppe senden
// PID 0 = aktuelle Prozessgruppe
$result = sapi_windows_generate_ctrl_event(PHP_WINDOWS_EVENT_CTRL_C, 0);
var_dump($result);

bool(true)

// Wichtig · Fallstricke

Plattform-Einschränkung: Die Funktion existiert ausschließlich unter Windows und nur in der CLI-SAPI. Vor dem Einsatz sollte immer function_exists('sapi_windows_generate_ctrl_event') aufgerufen werden, um einen fatalen Fehler auf anderen Systemen zu vermeiden.

Prozessgruppen-Verhalten: Windows-Konsolenanwendungen reagieren nur auf CTRL-Ereignisse, wenn sie zur selben Konsolen-Prozessgruppe gehören. Mit proc_open() gestartete Prozesse können u. U. eine eigene Prozessgruppe erhalten; das Verhalten hängt von den verwendeten Optionen und dem Betriebssystem ab.

Sicherheit: Das Senden von CTRL-Ereignissen an fremde Prozess-IDs kann unerwartete Auswirkungen haben. Stellen Sie sicher, dass die angegebene PID tatsächlich einem von Ihnen kontrollierten Kindprozess gehört.

Siehe auch

sapi_windows_set_ctrl_handler proc_open proc_get_status posix_kill