Signatur
Beschreibung
dio_truncate() gehört zur Direct-I/O-Erweiterung (PECL dio) und ermöglicht es, eine Datei auf eine bestimmte Länge zu kürzen oder – falls der angegebene Offset größer als die aktuelle Dateigröße ist – mit Null-Bytes aufzufüllen. Die Funktion arbeitet direkt auf Betriebssystem-Ebene und umgeht den PHP-Stream-Layer vollständig.
Ein typischer Anwendungsfall ist das gezielte Verkleinern einer Log-Datei oder das Reservieren von Speicherplatz in einer Datei. Im Gegensatz zu ftruncate(), das auf einem PHP-Stream-Handle operiert, arbeitet diese Funktion mit einem von dio_open() zurückgegebenen Ressource-Handle.
Wichtig: Die Dateiposition wird durch den Aufruf nicht verändert. Falls die Dateiposition nach dem Abschneiden hinter dem neuen Dateiende liegt, können nachfolgende Schreibvorgänge das neue Ende überschreiten oder unerwartete Ergebnisse liefern. In solchen Fällen sollte dio_seek() aufgerufen werden, um die Position zu korrigieren.
Die Direct-I/O-Erweiterung ist unter Windows-Systemen nicht verfügbar. Die Funktion setzt voraus, dass die Datei mit entsprechenden Schreibrechten geöffnet wurde.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $fd Pflicht | resource | Ein von dio_open() zurückgegebenes Datei-Handle, das mit Schreibberechtigung geöffnet wurde. |
|
| $offset Pflicht | int | Die gewünschte Zieldateigröße in Bytes. Bei 0 wird die Datei vollständig geleert. Ist der Wert größer als die aktuelle Dateigröße, wird die Datei mit Null-Bytes aufgefüllt. |
Rückgabewert
true zurück, wenn die Operation erfolgreich war, andernfalls false (z. B. bei fehlenden Schreibrechten oder ungültigem Handle).Beispiele
Datei auf 100 Bytes kürzen
<?php
// Datei mit Lese-/Schreibzugriff öffnen
$fd = dio_open('/tmp/beispiel.log', O_RDWR | O_CREAT);
if ($fd === false) {
die('Datei konnte nicht geöffnet werden.');
}
// Datei mit Beispielinhalt befüllen
dio_write($fd, str_repeat('A', 500));
// Datei auf 100 Bytes abschneiden
$result = dio_truncate($fd, 100);
if ($result) {
echo 'Datei erfolgreich auf 100 Bytes gekürzt.' . PHP_EOL;
} else {
echo 'Fehler beim Abschneiden der Datei.' . PHP_EOL;
}
dio_close($fd);Datei vollständig leeren (auf 0 Bytes kürzen)
<?php
$fd = dio_open('/tmp/logfile.log', O_RDWR | O_CREAT);
if ($fd === false) {
die('Datei konnte nicht geöffnet werden.');
}
// Datei komplett leeren
if (dio_truncate($fd, 0)) {
// Schreibposition zurücksetzen, da sie nach dem Truncate
// möglicherweise hinter dem Dateiende steht
dio_seek($fd, 0, SEEK_SET);
echo 'Log-Datei erfolgreich geleert.' . PHP_EOL;
}
dio_close($fd);// Wichtig · Fallstricke
Plattformverfügbarkeit: Die dio-Erweiterung (PECL) ist unter Windows nicht verfügbar und muss auf Unix/Linux-Systemen separat installiert werden (pecl install dio). Ohne installierte Erweiterung steht die Funktion nicht zur Verfügung.
Dateiposition: Nach dem Aufruf von dio_truncate() wird die interne Dateiposition nicht automatisch angepasst. Liegt die aktuelle Position hinter der neuen Dateigröße, sollte dio_seek() verwendet werden, um unerwartetes Verhalten bei nachfolgenden Lese- oder Schreiboperationen zu vermeiden.
Alternative: Für Standard-PHP-Streams (geöffnet mit fopen()) sollte stattdessen ftruncate() verwendet werden, da diese Funktion ausschließlich mit Direct-I/O-Handles arbeitet.