eio_ftruncate — Funktion · PHP-Referenz

Signatur

eio_ftruncate(mixed $fd, int $offset = 0, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

Beschreibung

eio_ftruncate() gehört zur eio-Erweiterung für asynchrone I/O-Operationen und entspricht dem POSIX-Systemaufruf ftruncate(2). Die Funktion kürzt oder erweitert die Datei, auf die der Dateideskriptor fd zeigt, auf exakt offset Bytes. Sie ist nicht-blockierend und gibt sofort eine Ressource zurück; das Ergebnis wird über die angegebene Callback-Funktion gemeldet.

Im Gegensatz zur blockierenden Variante ftruncate() von PHP eignet sich eio_ftruncate() besonders für Server-Anwendungen und Event-Loop-basierte Programme (z. B. in Kombination mit ReactPHP oder direkt mit dem eio-Event-Loop), in denen das Blockieren des Haupt-Threads vermieden werden muss.

Die Datei muss zuvor mit eio_open() oder einem anderen geeigneten Mechanismus geöffnet worden sein, der einen Integer-Dateideskriptor liefert. Ist offset größer als die aktuelle Dateigröße, wird die Datei mit Null-Bytes (\0) auf die gewünschte Größe aufgefüllt. Die Funktion arbeitet nicht mit PHP-Stream-Ressourcen, sondern ausschließlich mit nativen Dateideskriptoren.

Der optionale Parameter data wird unverändert an die Callback-Funktion weitergereicht und kann genutzt werden, um Kontext-Informationen durch den asynchronen Aufruf zu transportieren.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Nativer Integer-Dateideskriptor der Datei, die gekürzt werden soll. Dieser wird typischerweise von `eio_open()` im zugehörigen Callback geliefert.
$offset	int	0	Gewünschte Größe der Datei in Bytes nach dem Kürzen. Standardmäßig `0`, was die Datei vollständig leert. Ist dieser Wert größer als die aktuelle Dateigröße, wird die Datei mit Null-Bytes aufgefüllt.
$pri	int	EIO_PRI_DEFAULT	Priorität des Requests. Mögliche Werte: `EIO_PRI_MIN`, `EIO_PRI_DEFAULT`, `EIO_PRI_MAX`.
$callback	callable	NULL	Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Sie erhält die Argumente `$data`, `$result` und `$req`. `$result` ist `0` bei Erfolg, andernfalls `-1`.
$data	mixed	NULL	Beliebige Benutzerdaten, die unverändert an die Callback-Funktion übergeben werden. Nützlich, um Kontext-Informationen (z. B. Dateinamen, IDs) mitzutransportieren.

Rückgabewert

Typ

resource

Beschreibung

Gibt bei Erfolg eine eio_req-Ressource zurück, die den ausstehenden Request repräsentiert. Bei einem Fehler wird false zurückgegeben.

Beispiele

Datei auf 100 Bytes kürzen

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

eio_init();

$tmpFile = sys_get_temp_dir() . '/eio_ftruncate_test.txt';
file_put_contents($tmpFile, str_repeat('A', 500)); // 500 Bytes schreiben

// Datei asynchron öffnen
eio_open(
    $tmpFile,
    EIO_O_RDWR,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) use ($tmpFile) {
        if ($result === -1) {
            echo "Fehler beim Öffnen der Datei.\n";
            return;
        }

        $fd = $result; // nativer Dateideskriptor

        // Datei auf 100 Bytes kürzen
        eio_ftruncate(
            $fd,
            100,
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd, $data) {
                if ($result === 0) {
                    echo "Datei erfolgreich auf 100 Bytes gekürzt.\n";
                } else {
                    echo "Fehler beim Kürzen: " . eio_get_last_error($req) . "\n";
                }
                // Dateideskriptor schließen
                eio_close($fd);
            },
            $tmpFile
        );
    }
);

eio_event_loop();

// Ergebnis prüfen
echo "Aktuelle Dateigröße: " . filesize($tmpFile) . " Bytes\n";

Datei erfolgreich auf 100 Bytes gekürzt. Aktuelle Dateigröße: 100 Bytes

Datei vollständig leeren (auf 0 Bytes setzen)

<?php
eio_init();

$tmpFile = sys_get_temp_dir() . '/eio_empty_test.txt';
file_put_contents($tmpFile, 'Inhalt wird gelöscht.');

eio_open(
    $tmpFile,
    EIO_O_RDWR,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) use ($tmpFile) {
        if ($result === -1) {
            echo "Fehler beim Öffnen.\n";
            return;
        }
        $fd = $result;

        // Offset = 0 entspricht dem Standard — Datei wird geleert
        eio_ftruncate(
            $fd,
            0, // Standard-Offset
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd) {
                echo $result === 0
                    ? "Datei erfolgreich geleert.\n"
                    : "Fehler beim Leeren der Datei.\n";
                eio_close($fd);
            }
        );
    }
);

eio_event_loop();

echo "Dateigröße nach Leeren: " . filesize($tmpFile) . " Bytes\n";

Datei erfolgreich geleert. Dateigröße nach Leeren: 0 Bytes

// Wichtig · Fallstricke

Nativer Dateideskriptor erforderlich: eio_ftruncate() akzeptiert keinen PHP-Stream (also keine Ressource, die von fopen() zurückgegeben wird), sondern ausschließlich einen nativen Integer-Dateideskriptor. Diesen erhält man im Callback von eio_open().

Event-Loop: Die Funktion ist nicht-blockierend. Damit der Callback tatsächlich ausgeführt wird, muss der eio-Event-Loop laufen — entweder manuell über eio_event_loop() oder integriert in einen externen Event-Loop (z. B. via eio_get_event_stream() mit event- oder libevent-Erweiterungen).

Dateideskriptor schließen: Vergessen Sie nicht, den Dateideskriptor nach der Operation mit eio_close() zu schließen, um Ressourcenlecks zu vermeiden.

Plattformabhängigkeit: Die Funktion setzt eine POSIX-kompatible Umgebung voraus und ist unter Windows nicht verfügbar.

Siehe auch

eio_open eio_close eio_truncate eio_event_loop ftruncate