eio_dup2 — Funktion · PHP-Referenz

Signatur

eio_dup2(mixed $fd, mixed $fd2, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

Beschreibung

eio_dup2() dupliziert den Dateideskriptor fd auf den Zieldeskriptor fd2, analog zum POSIX-Systemaufruf dup2(2). Nach erfolgreicher Ausführung verweist fd2 auf dieselbe geöffnete Datei wie fd. War fd2 zuvor bereits geöffnet, wird er zuvor automatisch geschlossen.

Die Funktion arbeitet nicht-blockierend und gehört zur eio-Erweiterung, die auf libeio basiert. Sie eignet sich für Server-Anwendungen, bei denen Datei-I/O-Operationen den Hauptthread nicht blockieren sollen, z. B. in Kombination mit event- oder libevent-basierten Event-Loops.

Das Ergebnis der Operation wird asynchron über die angegebene $callback-Funktion gemeldet. Der Callback erhält als Parameter $data, den Rückgabewert der Operation sowie den Anforderungs-Ressourcen-Handle.

Typische Anwendungsfälle sind das Umleiten von Standard-Ein-/Ausgabe-Deskriptoren (stdin, stdout, stderr) auf andere Dateien oder Sockets in nicht-blockierendem Code.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Der Quell-Dateideskriptor, der dupliziert werden soll. Kann eine Ganzzahl (numerischer Dateideskriptor) oder ein Stream-Ressource-Handle sein.
$fd2 Pflicht	mixed		Der Ziel-Dateideskriptor, auf den `fd` dupliziert wird. War dieser bereits geöffnet, wird er zunächst geschlossen. Kann eine Ganzzahl oder ein Stream-Ressource-Handle sein.
$pri	int	EIO_PRI_DEFAULT	Priorität der Anforderung. Mögliche Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`.
$callback	callable	NULL	Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Sie erhält die Parameter `($data, $result, $req)`: `$data` sind die mitgegebenen Nutzdaten, `$result` ist der Rückgabewert des Systemaufrufs (bei Fehler `-1`), `$req` ist der Anforderungs-Handle.
$data	mixed	NULL	Beliebige Nutzdaten, die unverändert an die Callback-Funktion weitergegeben werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt bei Erfolg eine eio-Anforderungs-Ressource zurück, die zur Identifikation der asynchronen Operation verwendet werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

stdout auf eine Datei umleiten

<?php
// Voraussetzung: eio-Erweiterung ist geladen

$filePath = '/tmp/output.txt';

// Datei öffnen (schreibend, anlegen falls nicht vorhanden)
eio_open($filePath, EIO_O_WRONLY | EIO_O_CREAT | EIO_O_TRUNC, 0644, EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result === -1) {
            echo "Fehler beim Öffnen der Datei." . PHP_EOL;
            return;
        }

        $newFd = $result; // Dateideskriptor der geöffneten Datei
        $stdoutFd = 1;    // Dateideskriptor für stdout

        // stdout auf die geöffnete Datei duplizieren
        eio_dup2($newFd, $stdoutFd, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($newFd) {
            if ($result === -1) {
                echo "dup2 fehlgeschlagen." . PHP_EOL;
            } else {
                // Ab jetzt geht stdout in die Datei
                fwrite(STDOUT, "Diese Zeile wird in die Datei geschrieben." . PHP_EOL);
            }
            // Original-FD schließen
            eio_close($newFd);
            eio_event_loop();
        });

        eio_event_loop();
    }
);

eio_event_loop();
?>

Einfaches dup2 mit Fehlerprüfung im Callback

<?php
// Voraussetzung: eio-Erweiterung ist geladen

$srcFd = 1; // stdout
$dstFd = 3; // Zieldeskriptor

$req = eio_dup2($srcFd, $dstFd, EIO_PRI_DEFAULT, function ($data, $result, $req) {
    if ($result === -1) {
        $errno = eio_get_last_error($req);
        echo "dup2 fehlgeschlagen, Fehlercode: " . $errno . PHP_EOL;
    } else {
        echo "dup2 erfolgreich: Deskriptor dupliziert." . PHP_EOL;
    }
}, 'Nutzerdaten');

if ($req === false) {
    echo "eio_dup2 konnte nicht gestartet werden." . PHP_EOL;
} else {
    eio_event_loop();
}
?>

dup2 erfolgreich: Deskriptor dupliziert.

// Wichtig · Fallstricke

Achtung: Das versehentliche Schließen und Ersetzen wichtiger Dateideskriptoren wie 0 (stdin), 1 (stdout) oder 2 (stderr) kann zu unerwartetem Verhalten der Anwendung führen. Stelle sicher, dass fd2 kein benötigter Systemdeskriptor ist, bevor du ihn ersetzt.

Die eio-Erweiterung ist nur unter Unix-ähnlichen Systemen (Linux, macOS) verfügbar und nicht unter Windows lauffähig.

Da die Operation asynchron ist, hat der Rückgabewert von eio_dup2() selbst keine Bedeutung für den Erfolg des eigentlichen Systemaufrufs — dieser wird ausschließlich über den $result-Parameter des Callbacks signalisiert.

Siehe auch

eio_open eio_close eio_event_loop eio_get_last_error eio_dup2