ssh2_poll — Funktion · PHP-Referenz

Signatur

ssh2_poll(array &$desc, int $timeout): int

Beschreibung

ssh2_poll() ermöglicht es, mehrere SSH2-Ressourcen (Kanäle, Listener oder Streams) gleichzeitig auf Ereignisse wie eingehende Daten, beendete Verbindungen oder Fehler zu überwachen. Die Funktion blockiert dabei bis zu $timeout Millisekunden auf ein Ereignis – tritt ein Ereignis früher ein, kehrt sie sofort zurück. Dieses Konzept entspricht dem klassischen poll()-Systemaufruf unter Unix/Linux.

Das erste Argument $desc ist ein Array von assoziativen Arrays, von denen jedes einen überwachbaren SSH2-Stream oder eine Ressource sowie die gewünschten Ereignisse beschreibt. Mögliche Ereignis-Flags sind z. B. SSH2_POLL_WRITE, SSH2_POLL_READ und SSH2_POLL_ERR. Nach dem Aufruf werden die revents-Schlüssel der Einträge mit den tatsächlich eingetretenen Ereignissen befüllt.

Die Funktion ist besonders nützlich, wenn man mehrere SSH-Kanäle parallel verwaltet und nicht für jeden einzeln blockieren möchte. So lässt sich ein effizienter, nicht-blockierender Multiplexer für SSH2-Verbindungen umsetzen.

Hinweis: ssh2_poll() ist Teil der PECL-Erweiterung ssh2 und steht nicht in der PHP-Standardinstallation zur Verfügung. Die Funktion ist in der Praxis wenig dokumentiert und sollte mit Vorsicht eingesetzt werden.

Parameter

Name	Typ	Default	Beschreibung
$desc Pflicht	array		Ein Array von assoziativen Arrays. Jeder Eintrag beschreibt eine zu überwachende SSH2-Ressource und muss mindestens die Schlüssel `resource` (die SSH2-Stream-Ressource), `events` (eine Kombination aus `SSH2_POLL_*`-Konstanten) und `revents` (wird nach dem Aufruf mit den eingetretenen Ereignissen befüllt) enthalten. Das Array wird als Referenz übergeben.
$timeout Pflicht	int		Die maximale Wartezeit in Millisekunden. Der Aufruf blockiert höchstens so lange, bis ein Ereignis eintritt oder das Timeout abläuft. Ein Wert von `0` bewirkt eine sofortige Rückkehr (nicht-blockierend).

Rückgabewert

Typ

int

Beschreibung

Gibt die Anzahl der Deskriptoren zurück, für die Ereignisse eingetreten sind. Gibt 0 zurück, wenn das Timeout abgelaufen ist ohne Ereignisse. Bei einem Fehler wird -1 zurückgegeben.

Beispiele

Mehrere SSH2-Kanäle parallel auf Lesbarkeit prüfen

<?php
// Voraussetzung: PECL-Erweiterung ssh2 ist installiert
$connection = ssh2_connect('example.com', 22);
ssh2_auth_password($connection, 'user', 'geheim');

$channel1 = ssh2_exec($connection, 'ls -la /var/log');
$channel2 = ssh2_exec($connection, 'uptime');

// Stream-Modus auf nicht-blockierend setzen
stream_set_blocking($channel1, false);
stream_set_blocking($channel2, false);

$desc = [
    [
        'resource' => $channel1,
        'events'   => SSH2_POLL_READ | SSH2_POLL_ERR,
        'revents'  => 0,
    ],
    [
        'resource' => $channel2,
        'events'   => SSH2_POLL_READ | SSH2_POLL_ERR,
        'revents'  => 0,
    ],
];

// Bis zu 5000 ms (5 Sekunden) auf Ereignisse warten
$ready = ssh2_poll($desc, 5000);

if ($ready > 0) {
    foreach ($desc as $index => $entry) {
        if ($entry['revents'] & SSH2_POLL_READ) {
            echo "Kanal $index ist lesbar:\n";
            echo stream_get_contents($entry['resource']);
        }
        if ($entry['revents'] & SSH2_POLL_ERR) {
            echo "Fehler auf Kanal $index\n";
        }
    }
} elseif ($ready === 0) {
    echo "Timeout: Keine Ereignisse innerhalb von 5 Sekunden.\n";
} else {
    echo "Fehler beim Aufruf von ssh2_poll().\n";
}

Nicht-blockierendes Polling (Timeout = 0)

<?php
$connection = ssh2_connect('example.com', 22);
ssh2_auth_password($connection, 'user', 'geheim');

$channel = ssh2_exec($connection, 'sleep 2 && echo fertig');
stream_set_blocking($channel, false);

$desc = [
    [
        'resource' => $channel,
        'events'   => SSH2_POLL_READ,
        'revents'  => 0,
    ],
];

// Sofortige Prüfung ohne Blockierung
$ready = ssh2_poll($desc, 0);

if ($ready === 0) {
    echo "Noch keine Daten verfügbar (nicht-blockierend).\n";
} elseif ($ready > 0 && ($desc[0]['revents'] & SSH2_POLL_READ)) {
    echo stream_get_contents($channel);
}

Noch keine Daten verfügbar (nicht-blockierend).

// Wichtig · Fallstricke

PECL-Erweiterung: ssh2_poll() ist Teil der PECL-Erweiterung ssh2 (libssh2-basiert) und muss separat installiert werden (pecl install ssh2). Sie ist nicht Bestandteil der PHP-Standardinstallation.

Spärliche Dokumentation: Die Funktion ist in der offiziellen PHP-Dokumentation kaum beschrieben. Verhalten, Rückgabewerte und Fehlerbehandlung können je nach Version der ssh2-Erweiterung und der zugrundeliegenden libssh2-Bibliothek variieren.

Stream-Modus: Für zuverlässiges Multiplexing sollten alle überwachten Streams zuvor mit stream_set_blocking($stream, false) in den nicht-blockierenden Modus versetzt werden, um ein Hängenbleiben beim Lesen zu verhindern.

Ressourcenmanagement: Nicht mehr benötigte SSH2-Kanäle sollten explizit mit fclose() oder ssh2_exec()-Rückgaben geschlossen werden, um Ressourcenlecks zu vermeiden.

Siehe auch

ssh2_connect ssh2_exec ssh2_auth_password stream_set_blocking stream_select