ftruncate()

La función ftruncate() en PHP redimensiona un archivo abierto a un número exacto de bytes. Puede tanto reducir un archivo (cortando todo lo que supere una longitud determinada) como ampliarlo (rellenando el espacio adicional con bytes null). Esta página explica la sintaxis, el valor de retorno, las reglas sobre el puntero de archivo y los usos prácticos más comunes — limpiar un log, corregir un registro dañado o preasignar espacio — con ejemplos ejecutables.

Qué hace la función ftruncate()

ftruncate() trunca un archivo abierto a la longitud que se especifique, medida en bytes:

• Si el archivo es mayor que length, los bytes sobrantes se descartan.
• Si el archivo es menor que length, se extiende y la nueva área se rellena con bytes null (\0).
• Si length es igual a 0, el archivo queda vacío — una forma habitual de limpiar un archivo sin eliminarlo.

Devuelve true en caso de éxito y false en caso de error. Es importante destacar que ftruncate() no mueve el puntero interno del archivo. Si escribiste hasta el byte 50 y luego truncas a 10 bytes, el puntero sigue en 50, por lo que la siguiente escritura comenzaría ahí y volvería a extender el archivo con bytes null. Usa rewind() o fseek() para reposicionar el puntero después.

Sintaxis

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

• $stream — el puntero de archivo devuelto por fopen(). El archivo debe abrirse en un modo de escritura (r+, w, w+, a+, etc.). Abrirlo con r (solo lectura) hace que ftruncate() falle.
• $size — el nuevo tamaño del archivo en bytes (un entero no negativo).

Cómo usar ftruncate()

El patrón siempre consta de los mismos tres pasos:

1. Abrir el archivo en modo de escritura con fopen().
2. Llamar a ftruncate() con el puntero de archivo y el tamaño objetivo.
3. Cerrar el archivo con fclose().

El siguiente ejemplo escribe una cadena conocida, la trunca a 5 bytes y lee el resultado para que puedas ver exactamente qué queda:

<?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);

La salida es:

Hello

Solo Hello permanece porque el archivo se recortó a 5 bytes. Observa la llamada a rewind() — sin ella, fread() comenzaría en el byte 13 (más allá del final) y no devolvería nada.

Ampliar un archivo con bytes null

Cuando $size es mayor que el archivo actual, ftruncate() lo extiende y rellena la nueva región con \0. Esto es útil para preasignar un archivo de tamaño fijo:

<?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);

La salida es:

8 bytes

El archivo ahora tiene 8 bytes — el abc original seguido de cinco bytes null (\0). La llamada a clearstatcache() importa porque PHP almacena en caché el resultado de funciones basadas en stat como filesize() dentro de una solicitud; si ya habías leído el tamaño del archivo antes, el valor en caché podría estar desactualizado tras un truncado.

Casos de uso comunes

• Limpiar un archivo en su lugar. ftruncate($file, 0) vacía un archivo de log o caché manteniendo su inodo, permisos y cualquier otro manejador abierto. Esto es más seguro que eliminarlo y recrearlo.
• Eliminar un registro final. Lee el archivo, encuentra dónde comienza la última entrada y trunca hasta ese desplazamiento para descartarla sin reescribir todo el archivo.
• Corregir un archivo parcialmente escrito. Si una escritura fue interrumpida, truncar hasta una longitud conocida y válida restaura un estado correcto.
• Preasignar espacio. Reserva un archivo de tamaño fijo de antemano (por ejemplo, un índice binario) antes de rellenarlo.

Aspectos a tener en cuenta

• Los manejadores de solo lectura fallan. Abrir con r y llamar a ftruncate() devuelve false y emite una advertencia. Usa r+ si necesitas conservar el contenido existente pero también escribir.
• El puntero no se mueve. Siempre usa rewind() o fseek() antes de leer o agregar contenido tras un truncado, o podrías generar relleno inesperado con bytes null.
• Caché de stat obsoleta. filesize() y funciones similares pueden reportar el tamaño anterior justo después de truncar; llama a clearstatcache() para obtener el valor actual.
• length está en bytes, no en caracteres. Con texto multibyte (UTF-8), truncar a mitad de un carácter puede corromper el último carácter.

Funciones relacionadas

• fopen() — abrir el archivo antes de truncarlo.
• fwrite() — escribir datos en el archivo.
• fread() — leer el contenido del archivo.
• fseek() / rewind() — reposicionar el puntero tras el truncado.
• fclose() — cerrar el archivo cuando hayas terminado.

Conclusión

ftruncate() es la forma precisa de redimensionar un archivo abierto en PHP — reduciéndolo al cortar los bytes finales, o ampliándolo con relleno de bytes null. Los aspectos clave a recordar son que el archivo debe estar abierto en modo de escritura, que la función nunca mueve el puntero del archivo y que puede ser necesario llamar a clearstatcache() para ver el nuevo tamaño. Usado junto con fopen(), fwrite() y fclose(), gestiona tareas que van desde limpiar logs hasta reparar archivos parcialmente escritos.

Práctica