ftruncate()

La funzione ftruncate() in PHP ridimensiona un file aperto a un numero esatto di byte. Può sia ridurre un file (eliminando tutto ciò che supera una determinata lunghezza) che espanderlo (riempiendo lo spazio aggiuntivo con byte null). Questa pagina spiega la sintassi, il valore restituito, le regole relative al puntatore di file e gli usi pratici più comuni — svuotare un log, correggere un record corrotto o pre-allocare spazio — con esempi eseguibili.

Cosa fa la funzione ftruncate()

ftruncate() tronca un file aperto alla lunghezza specificata, misurata in byte:

• Se il file è più grande di length, i byte in eccesso vengono eliminati.
• Se il file è più piccolo di length, viene esteso e la nuova area viene riempita con byte null (\0).
• Se length è uguale a 0, il file viene svuotato — un modo comune per cancellare un file senza eliminarlo.

Restituisce true in caso di successo e false in caso di errore. È importante notare che ftruncate() non sposta il puntatore interno del file. Se hai scritto fino al byte 50 e poi tronchi a 10 byte, il puntatore rimane a 50, quindi la scrittura successiva ripartirebbe da lì, estendendo nuovamente il file con byte null. Usa rewind() o fseek() per riposizionare il puntatore in seguito.

Sintassi

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

• $stream — il puntatore al file restituito da fopen(). Il file deve essere aperto in modalità scrivibile (r+, w, w+, a+, ecc.). L'apertura con r (sola lettura) fa fallire ftruncate().
• $size — la nuova dimensione del file in byte (un intero non negativo).

Come usare ftruncate()

Il pattern è sempre composto dagli stessi tre passaggi:

1. Aprire il file in modalità scrivibile con fopen().
2. Chiamare ftruncate() con il puntatore al file e la dimensione target.
3. Chiudere il file con fclose().

L'esempio seguente scrive una stringa nota, la tronca a 5 byte e rilegge il risultato in modo da vedere esattamente cosa rimane:

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

L'output è:

Hello

Rimane solo Hello perché il file è stato tagliato a 5 byte. Nota la chiamata a rewind() — senza di essa fread() partirebbe dal byte 13 (oltre la fine) e non restituirebbe nulla.

Espandere un file con byte null

Quando $size è maggiore della dimensione attuale del file, ftruncate() lo estende e riempie la nuova regione con \0. Questo è utile per pre-allocare un file di dimensione fissa:

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

L'output è:

8 bytes

Il file ora è di 8 byte — l'originale abc seguito da cinque byte null (\0). La chiamata a clearstatcache() è importante perché PHP memorizza nella cache il risultato delle funzioni basate su stat come filesize() all'interno di una richiesta; se avevi già letto la dimensione del file in precedenza, il valore memorizzato potrebbe essere obsoleto dopo un troncamento.

Casi d'uso comuni

• Svuotare un file sul posto. ftruncate($file, 0) svuota un file di log o di cache mantenendo il suo inode, i permessi e qualsiasi altro handle aperto. È più sicuro che eliminarlo e ricrearlo.
• Rimuovere un record finale. Leggi il file, trova il punto in cui inizia l'ultimo elemento e tronca fino a quell'offset per eliminarlo senza riscrivere l'intero file.
• Correggere un file scritto parzialmente. Se una scrittura è stata interrotta, troncare il file a una lunghezza nota e valida ripristina uno stato consistente.
• Pre-allocare spazio. Riservare in anticipo un file di dimensione fissa (ad esempio, un indice binario) prima di riempirlo.

Avvertenze

• Gli handle in sola lettura falliscono. Aprire con r e chiamare ftruncate() restituisce false ed emette un avviso. Usa r+ se devi mantenere il contenuto esistente ma hai comunque bisogno di scrivere.
• Il puntatore non si sposta. Esegui sempre rewind() o fseek() prima di leggere o accodare dopo un troncamento, altrimenti potresti creare padding inatteso con byte null.
• Cache stat obsoleta. filesize() e funzioni simili potrebbero riportare la vecchia dimensione subito dopo il troncamento; chiama clearstatcache() per ottenere il valore aggiornato.
• length è in byte, non in caratteri. Con testo multi-byte (UTF-8), troncare nel mezzo di un carattere può corrompere l'ultimo carattere.

Funzioni correlate

• fopen() — aprire il file prima di troncare.
• fwrite() — scrivere dati nel file.
• fread() — rileggere il contenuto del file.
• fseek() / rewind() — riposizionare il puntatore dopo il troncamento.
• fclose() — chiudere il file al termine.

Conclusione

ftruncate() è il modo preciso per ridimensionare un file aperto in PHP — riducendolo eliminando i byte finali, oppure espandendolo con byte null di padding. Le cose fondamentali da ricordare sono che il file deve essere aperto in modalità scrivibile, che la funzione non sposta mai il puntatore del file, e che potrebbe essere necessario chiamare clearstatcache() per vedere la nuova dimensione. Usata insieme a fopen(), fwrite() e fclose(), gestisce operazioni che vanno dalla pulizia dei log alla riparazione di file scritti parzialmente.

Pratica