eio_seek — Funktion · PHP-Referenz

Signatur

eio_seek(mixed $fd, int $offset, int $whence, int $pri = EIO_PRI_DEFAULT, callable $callback = null, mixed $data = null): resource

Beschreibung

eio_seek ist Teil der EIO-Erweiterung (asynchrone POSIX-I/O-Operationen) und entspricht dem nicht-blockierenden Pendant zum systemnahen lseek(2)-Aufruf. Die Funktion verschiebt den Lese-/Schreibzeiger eines offenen Dateideskriptors auf eine neue Position, ohne den aufrufenden Prozess zu blockieren.

Der Parameter whence steuert, wie der offset interpretiert wird: SEEK_SET setzt den Zeiger auf den absoluten Byte-Wert, SEEK_CUR relativ zur aktuellen Position und SEEK_END relativ zum Dateiende. Das Ergebnis der Operation wird asynchron über die callback-Funktion gemeldet.

Sinnvoll ist eio_seek in ereignisgesteuerten Anwendungen (z. B. mit ReactPHP, Ev oder dem EIO-Eventloop), bei denen blockierende I/O-Operationen die Hauptschleife aufhalten würden. Typische Anwendungsfälle sind das gezielte Lesen großer Dateien an bestimmten Positionen oder das partielle Schreiben in Binärdateien.

Der Rückgabewert ist eine EIO-Request-Ressource, mit der die Anforderung bei Bedarf über eio_cancel() abgebrochen werden kann. Im Callback erhält man die neue Dateiposition als $result-Parameter.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Geöffneter Dateideskriptor – entweder eine PHP-Stream-Ressource oder ein numerischer Dateideskriptor (z. B. via `eio_open` erzeugt).
$offset Pflicht	int		Byte-Offset, um den die Position verschoben wird. Die Bedeutung hängt von `whence` ab.
$whence Pflicht	int		Legt fest, wie `offset` interpretiert wird: `SEEK_SET` (absolut), `SEEK_CUR` (relativ zur aktuellen Position) oder `SEEK_END` (relativ zum Dateiende).
$pri	int	EIO_PRI_DEFAULT	Priorität der Anforderung. Mögliche Werte: `EIO_PRI_MIN`, `EIO_PRI_DEFAULT`, `EIO_PRI_MAX`.
$callback	callable	null	Wird nach Abschluss der Operation aufgerufen. Signatur: `function($data, $result, $req)`. `$result` enthält die neue Dateiposition oder `-1` im Fehlerfall.
$data	mixed	null	Beliebige benutzerdefinierte Daten, die unverändert an den `callback` als erstes Argument weitergegeben werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt eine EIO-Request-Ressource zurück, die die ausstehende Anforderung repräsentiert. Im Fehlerfall (bei ungültigen Argumenten) wird false zurückgegeben. Das eigentliche Ergebnis der Seek-Operation (neue Position) wird asynchron im Callback als $result übergeben.

Beispiele

Datei öffnen, Zeiger verschieben und Inhalt ab Position lesen

<?php
eio_init();

$tmpFile = tempnam(sys_get_temp_dir(), 'eio_');
file_put_contents($tmpFile, 'Hello, World!');

// Datei asynchron öffnen
eio_open($tmpFile, EIO_O_RDONLY, 0, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($tmpFile) {
    if ($result < 0) {
        echo "Fehler beim Öffnen der Datei\n";
        return;
    }
    $fd = $result;

    // Zeiger auf Byte 7 setzen (absolut)
    eio_seek($fd, 7, SEEK_SET, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($fd) {
        echo "Neue Position: $result\n"; // 7

        // 6 Bytes ab der neuen Position lesen
        eio_read($fd, 6, $result, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($fd) {
            echo "Gelesen: $result\n"; // World!
            eio_close($fd);
        });
    });
});

eio_event_loop();
?>

Neue Position: 7 Gelesen: World!

Zeiger relativ zum Dateiende setzen (SEEK_END)

<?php
eio_init();

$tmpFile = tempnam(sys_get_temp_dir(), 'eio_');
file_put_contents($tmpFile, 'ABCDEFGHIJ'); // 10 Bytes

eio_open($tmpFile, EIO_O_RDONLY, 0, EIO_PRI_DEFAULT, function ($data, $fd, $req) {
    if ($fd < 0) {
        echo "Fehler beim Öffnen\n";
        return;
    }

    // 3 Bytes vor dem Ende -> Position 7
    eio_seek($fd, -3, SEEK_END, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($fd) {
        echo "Position: $result\n"; // 7

        eio_read($fd, 3, $result, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($fd) {
            echo "Letzten 3 Zeichen: $result\n"; // HIJ
            eio_close($fd);
        });
    });
});

eio_event_loop();
?>

Position: 7 Letzten 3 Zeichen: HIJ

// Wichtig · Fallstricke

Voraussetzung: Die EIO-Erweiterung (pecl install eio) muss installiert und aktiviert sein. Sie ist standardmäßig nicht in PHP enthalten.

Eventloop: eio_seek ist nicht-blockierend und funktioniert nur korrekt innerhalb eines EIO-Eventloops (eio_event_loop()) oder in Kombination mit libevent/libev-Integrationen. Außerhalb eines Loops werden Callbacks niemals ausgeführt.

Fehlerbehandlung: Im Fehlerfall liefert $result im Callback den Wert -1. Der genaue Fehler lässt sich mit eio_get_last_error($req) ermitteln.

Kompatibilität: Die numerischen Konstanten SEEK_SET, SEEK_CUR und SEEK_END entsprechen den POSIX-Standardwerten 0, 1 und 2 und sind in PHP als Kern-Konstanten verfügbar.

Siehe auch

eio_open eio_read eio_write eio_close eio_cancel eio_event_loop fseek