ftruncate()

Die Funktion ftruncate() in PHP ändert die Größe einer geöffneten Datei auf eine exakte Anzahl von Bytes. Sie kann eine Datei sowohl verkleinern (alles nach einer bestimmten Länge abschneiden) als auch vergrößern (den zusätzlichen Bereich mit Null-Bytes auffüllen). Diese Seite erklärt die Syntax, den Rückgabewert, die Regeln zum Dateizeiger und die gängigen Anwendungsfälle — Logs leeren, fehlerhafte Datensätze bereinigen oder Speicherplatz vorbelegen — mit ausführbaren Beispielen.

Was die Funktion ftruncate() tut

ftruncate() kürzt eine geöffnete Datei auf die angegebene Länge in Bytes:

• Ist die Datei größer als length, werden die überschüssigen Bytes verworfen.
• Ist die Datei kleiner als length, wird sie erweitert und der neue Bereich mit Null-Bytes (\0) gefüllt.
• Ist length gleich 0, wird die Datei geleert — eine gängige Methode, eine Datei zu leeren, ohne sie zu löschen.

Die Funktion gibt bei Erfolg true und bei Fehler false zurück. Wichtig: ftruncate() verschiebt den internen Dateizeiger nicht. Haben Sie bis Byte 50 geschrieben und kürzen die Datei auf 10 Bytes, steht der Zeiger immer noch bei 50. Der nächste Schreibvorgang würde dort beginnen und die Datei erneut mit Null-Bytes auffüllen. Verwenden Sie anschließend rewind() oder fseek(), um den Zeiger neu zu positionieren.

Syntax

ftruncate(resource $stream, int $size): bool

• $stream — der von fopen() zurückgegebene Dateizeiger. Die Datei muss in einem schreibbaren Modus geöffnet sein (r+, w, w+, a+ usw.). Bei r (nur lesen) schlägt ftruncate() fehl.
• $size — die neue Dateigröße in Bytes (eine nicht-negative ganze Zahl).

Verwendung von ftruncate()

Das Muster besteht immer aus denselben drei Schritten:

1. Datei mit fopen() in einem schreibbaren Modus öffnen.
2. ftruncate() mit dem Dateizeiger und der Zielgröße aufrufen.
3. Datei mit fclose() schließen.

Das folgende Beispiel schreibt einen bekannten String, kürzt ihn auf 5 Bytes und liest das Ergebnis zurück, damit Sie genau sehen, was erhalten bleibt:

<?php

$filename = 'demo.txt';

// Open for reading and writing; create if it does not exist.
$file = fopen($filename, 'w+');

fwrite($file, 'Hello, World!'); // 13 bytes
ftruncate($file, 5);            // keep only the first 5 bytes

rewind($file);                  // pointer was at 13 — move it back to 0
echo fread($file, 1024);        // Hello

fclose($file);

Die Ausgabe lautet:

Hello

Nur Hello bleibt übrig, da die Datei auf 5 Bytes gekürzt wurde. Beachten Sie den rewind()-Aufruf — ohne ihn würde fread() bei Byte 13 (hinter dem Ende) beginnen und nichts zurückgeben.

Eine Datei mit Null-Bytes vergrößern

Ist $size größer als die aktuelle Datei, erweitert ftruncate() sie und füllt den neuen Bereich mit \0. Dies ist nützlich, um eine Datei mit fester Größe vorab anzulegen:

<?php

$file = fopen('padded.txt', 'w+');

fwrite($file, 'abc');     // 3 bytes
ftruncate($file, 8);      // grow to 8 bytes; 5 null bytes added

clearstatcache();         // discard any cached stat info
echo filesize('padded.txt') . " bytes\n";

fclose($file);

Die Ausgabe lautet:

8 bytes

Die Datei hat jetzt 8 Bytes — das ursprüngliche abc gefolgt von fünf null (\0) Bytes. Der Aufruf von clearstatcache() ist wichtig, weil PHP das Ergebnis von stat-basierten Funktionen wie filesize() innerhalb einer Anfrage zwischenspeichert. Wenn Sie die Dateigröße bereits zuvor gelesen haben, könnte der gecachte Wert nach einem Truncate veraltet sein.

Häufige Anwendungsfälle

• Eine Datei an Ort und Stelle leeren. ftruncate($file, 0) leert eine Log- oder Cache-Datei, während ihr Inode, ihre Berechtigungen und alle anderen offenen Handles erhalten bleiben. Dies ist sicherer als Löschen und Neuerstellen.
• Einen abschließenden Datensatz entfernen. Datei lesen, den Beginn des letzten Eintrags finden und auf diesen Offset kürzen, um ihn zu entfernen, ohne die gesamte Datei neu zu schreiben.
• Eine teilweise geschriebene Datei reparieren. Wurde ein Schreibvorgang unterbrochen, stellt das Kürzen auf eine bekannte gültige Länge einen konsistenten Zustand wieder her.
• Speicherplatz vorbelegen. Eine Datei fester Größe (z. B. ein binärer Index) vorab reservieren, bevor sie befüllt wird.

Häufige Fehler

• Nur-Lese-Handles schlagen fehl. Wird mit r geöffnet und ftruncate() aufgerufen, gibt die Funktion false zurück und gibt eine Warnung aus. Verwenden Sie r+, wenn Sie vorhandene Inhalte behalten und trotzdem schreiben möchten.
• Der Zeiger wird nicht verschoben. Führen Sie immer rewind() oder fseek() aus, bevor Sie nach einem Truncate lesen oder anhängen, sonst können unerwartete Null-Byte-Auffüllungen entstehen.
• Veralteter Stat-Cache. filesize() und ähnliche Funktionen können kurz nach dem Kürzen noch die alte Größe melden; rufen Sie clearstatcache() auf, um den aktuellen Wert zu erhalten.
• length ist in Bytes, nicht in Zeichen. Bei mehrbytigen (UTF-8) Texten kann ein Truncate mitten in einem Zeichen das letzte Zeichen beschädigen.

Verwandte Funktionen

• fopen() — Datei vor dem Kürzen öffnen.
• fwrite() — Daten in die Datei schreiben.
• fread() — Dateiinhalt zurücklesen.
• fseek() / rewind() — Zeiger nach dem Kürzen neu positionieren.
• fclose() — Datei schließen, wenn Sie fertig sind.

Fazit

ftruncate() ist die präzise Methode, um eine geöffnete Datei in PHP zu verkleinern — durch Abschneiden überschüssiger Bytes oder Vergrößern mit Null-Byte-Auffüllung. Die wichtigsten Punkte: Die Datei muss in einem schreibbaren Modus geöffnet sein, die Funktion verschiebt den Dateizeiger nie, und clearstatcache() kann erforderlich sein, um die neue Größe zu sehen. In Kombination mit fopen(), fwrite() und fclose() eignet sie sich für Aufgaben vom Leeren von Logs bis hin zur Reparatur teilweise geschriebener Dateien.

Übungen