ftruncate()

La fonction ftruncate() en PHP redimensionne un fichier ouvert à un nombre exact d'octets. Elle peut à la fois réduire un fichier (en supprimant tout ce qui dépasse une longueur donnée) et l'agrandir (en remplissant l'espace supplémentaire avec des octets null). Cette page explique la syntaxe, la valeur de retour, les règles concernant le pointeur de fichier et les utilisations courantes — effacer un journal, corriger un enregistrement corrompu ou pré-allouer de l'espace — avec des exemples exécutables.

Ce que fait la fonction ftruncate()

ftruncate() tronque un fichier ouvert à la longueur que vous spécifiez, mesurée en octets :

• Si le fichier est plus grand que length, les octets en excès sont supprimés.
• Si le fichier est plus petit que length, il est étendu et la nouvelle zone est remplie d'octets null (\0).
• Si length est égal à 0, le fichier est vidé — une façon courante d'effacer un fichier sans le supprimer.

Elle renvoie true en cas de succès et false en cas d'échec. Il est important de noter que ftruncate() ne déplace pas le pointeur interne du fichier. Si vous avez écrit jusqu'à l'octet 50 puis tronqué à 10 octets, le pointeur est toujours à 50, donc votre prochaine écriture démarrerait là et réétendrait le fichier avec des octets null. Utilisez rewind() ou fseek() pour repositionner le pointeur ensuite.

Syntaxe

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

• $stream — le pointeur de fichier retourné par fopen(). Le fichier doit être ouvert en mode inscriptible (r+, w, w+, a+, etc.). L'ouverture avec r (lecture seule) fait échouer ftruncate().
• $size — la nouvelle taille du fichier en octets (un entier non négatif).

Comment utiliser ftruncate()

Le schéma est toujours le même en trois étapes :

1. Ouvrir le fichier en mode inscriptible avec fopen().
2. Appeler ftruncate() avec le pointeur de fichier et la taille cible.
3. Fermer le fichier avec fclose().

L'exemple ci-dessous écrit une chaîne connue, la tronque à 5 octets et relit le résultat afin que vous puissiez voir exactement ce qui subsiste :

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

Le résultat est :

Hello

Seul Hello reste parce que le fichier a été réduit à 5 octets. Notez l'appel à rewind() — sans lui, fread() démarrerait à l'octet 13 (après la fin) et ne renverrait rien.

Agrandir un fichier avec des octets null

Lorsque $size est supérieur à la taille actuelle du fichier, ftruncate() l'étend et remplit la nouvelle région avec \0. Ceci est utile pour pré-allouer un fichier de taille fixe :

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

Le résultat est :

8 bytes

Le fichier fait maintenant 8 octets — le abc original suivi de cinq octets null (\0). L'appel à clearstatcache() est important car PHP met en cache le résultat des fonctions basées sur stat comme filesize() au cours d'une requête ; si vous aviez déjà lu la taille du fichier auparavant, la valeur en cache pourrait être périmée après une troncature.

Cas d'utilisation courants

• Vider un fichier en place. ftruncate($file, 0) vide un fichier journal ou de cache tout en conservant son inode, ses permissions et tout autre descripteur ouvert. C'est plus sûr que de le supprimer et de le recréer.
• Supprimer un enregistrement de fin. Lire le fichier, trouver l'endroit où commence le dernier enregistrement, et tronquer jusqu'à cet offset pour le supprimer sans réécrire tout le fichier.
• Corriger un fichier partiellement écrit. Si une écriture a été interrompue, tronquer jusqu'à une longueur valide connue restaure un état valide.
• Pré-allouer de l'espace. Réserver un fichier de taille fixe à l'avance (par exemple, un index binaire) avant de le remplir.

Points d'attention

• Les descripteurs en lecture seule échouent. Ouvrir avec r et appeler ftruncate() renvoie false et émet un avertissement. Utilisez r+ si vous devez conserver le contenu existant tout en pouvant écrire.
• Le pointeur ne se déplace pas. Faites toujours un rewind() ou fseek() avant de lire ou d'ajouter après une troncature, sinon vous risquez de créer un rembourrage inattendu avec des octets null.
• Cache stat périmé. filesize() et les fonctions similaires peuvent indiquer l'ancienne taille juste après une troncature ; appelez clearstatcache() pour obtenir la valeur actuelle.
• length est en octets, pas en caractères. Avec du texte multi-octets (UTF-8), tronquer au milieu d'un caractère peut corrompre le dernier caractère.

Fonctions associées

• fopen() — ouvrir le fichier avant de le tronquer.
• fwrite() — écrire des données dans le fichier.
• fread() — relire le contenu du fichier.
• fseek() / rewind() — repositionner le pointeur après la troncature.
• fclose() — fermer le fichier une fois terminé.

Conclusion

ftruncate() est la méthode précise pour redimensionner un fichier ouvert en PHP — le réduire en coupant les octets de fin, ou l'agrandir avec des octets null. Les points essentiels à retenir sont que le fichier doit être ouvert en mode inscriptible, que la fonction ne déplace jamais le pointeur de fichier, et que clearstatcache() peut être nécessaire pour voir la nouvelle taille. Utilisée avec fopen(), fwrite() et fclose(), elle gère des tâches allant de l'effacement des journaux à la réparation de fichiers partiellement écrits.

Pratique