eio_truncate — Funktion · PHP-Referenz

Signatur

eio_truncate(string $path, int $offset = 0, int $pri = EIO_PRI_DEFAULT, callable $callback = null, mixed $data = null): resource|false

Beschreibung

eio_truncate() ist die asynchrone Entsprechung des POSIX-Systemaufrufs truncate(2). Sie kürzt (oder verlängert) die Datei unter dem angegebenen Pfad auf exakt offset Bytes, ohne den aufrufenden Prozess zu blockieren. Die eigentliche Operation wird von einem Worker-Thread ausgeführt; sobald sie abgeschlossen ist, wird die callback-Funktion aufgerufen.

Ist die Datei länger als offset Bytes, werden die überschüssigen Daten verworfen. Ist sie kürzer, wird sie mit Null-Bytes (\0) auf die gewünschte Größe aufgefüllt. Das Verhalten entspricht damit dem der blockierenden PHP-Funktion ftruncate(), arbeitet aber nicht-blockierend im Event-Loop.

Diese Funktion eignet sich besonders in reaktiven Anwendungen oder Servern, die auf libeio bzw. eio setzen (z. B. zusammen mit event oder libuv), wenn Dateioperationen viele parallele I/O-Zyklen durchlaufen müssen, ohne den Hauptprozess zu blockieren.

Die Funktion gibt sofort ein Request-Ressource-Objekt zurück. Der Fortschritt der Operation und eventuelle Fehler werden ausschließlich im Callback gemeldet.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Pfad zur Datei, die gekürzt oder verlängert werden soll. Der Pfad muss für den laufenden Prozess zugänglich und schreibbar sein.
$offset	int	0	Zielgröße der Datei in Bytes. Standardmäßig `0`, wodurch die Datei vollständig geleert wird. Muss ein nicht-negativer Ganzzahlwert sein.
$pri	int	EIO_PRI_DEFAULT	Priorität der Anfrage. Mögliche Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`. Steuert die Reihenfolge der Abarbeitung in der Worker-Queue.
$callback	callable	null	Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Signatur: `function(mixed $data, int $result, resource $req): void`. `$result` enthält `0` bei Erfolg, andernfalls `-1`.
$data	mixed	null	Beliebige benutzerdefinierte Daten, die unverändert an den Callback weitergereicht werden. Nützlich zur Zustandsübergabe ohne globale Variablen.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt bei Erfolg eine eio-Request-Ressource zurück, mit der die Anfrage z. B. über eio_cancel() abgebrochen werden kann. Gibt false zurück, wenn die Anfrage nicht erstellt werden konnte.

Beispiele

Datei auf 100 Bytes kürzen

<?php
// eio-Erweiterung muss geladen sein
$tmpFile = sys_get_temp_dir() . '/eio_test.txt';
file_put_contents($tmpFile, str_repeat('A', 500)); // 500 Bytes schreiben

eio_truncate(
    $tmpFile,
    100,
    EIO_PRI_DEFAULT,
    function (mixed $data, int $result, $req): void {
        if ($result === 0) {
            echo "Datei erfolgreich auf {$data['size']} Bytes gekürzt.\n";
            echo 'Aktuelle Dateigröße: ' . filesize($data['path']) . ' Bytes' . PHP_EOL;
        } else {
            echo 'Fehler beim Kürzen: ' . eio_get_last_error($req) . PHP_EOL;
        }
    },
    ['path' => $tmpFile, 'size' => 100]
);

eio_event_loop();

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

Datei vollständig leeren (auf 0 Bytes setzen)

<?php
$logFile = '/tmp/app.log';
file_put_contents($logFile, "Alter Log-Inhalt\n");

$req = eio_truncate(
    $logFile,
    0,
    EIO_PRI_DEFAULT,
    function (mixed $data, int $result, $req): void {
        if ($result === 0) {
            echo "Log-Datei geleert. Größe: " . filesize($data) . " Bytes\n";
        } else {
            echo 'Fehler: ' . eio_get_last_error($req) . PHP_EOL;
        }
    },
    $logFile
);

if ($req === false) {
    echo 'eio_truncate-Anfrage konnte nicht erstellt werden.' . PHP_EOL;
} else {
    eio_event_loop();
}

Log-Datei geleert. Größe: 0 Bytes

// Wichtig · Fallstricke

Berechtigungen: Der Prozess benötigt Schreibrechte auf die Datei. Fehlt die Berechtigung, schlägt die Operation im Callback mit $result === -1 fehl.

Asynchronität: eio_truncate() kehrt sofort zurück. Die tatsächliche Operation findet erst statt, wenn der Event-Loop (z. B. via eio_event_loop()) läuft. Ohne aktiven Event-Loop wird der Callback niemals ausgeführt.

Kein Datei-Handle: Im Gegensatz zu ftruncate() arbeitet eio_truncate() mit dem Dateipfad, nicht mit einem geöffneten Datei-Handle. Für geöffnete Handles steht eio_ftruncate() zur Verfügung.

Clearstatcache: Da PHP Dateistatistiken intern cached, sollte nach dem Callback clearstatcache() aufgerufen werden, damit Funktionen wie filesize() den aktuellen Wert zurückgeben.

Siehe auch

eio_ftruncate eio_open eio_cancel eio_event_loop ftruncate eio_get_last_error