ftruncate()

A função ftruncate() em PHP redimensiona um arquivo aberto para um número exato de bytes. Ela pode tanto reduzir um arquivo (cortando tudo após um determinado tamanho) quanto aumentá-lo (preenchendo o espaço extra com bytes nulos). Esta página explica a sintaxe, o valor de retorno, as regras sobre o ponteiro de arquivo e os usos práticos mais comuns — limpar um log, corrigir um registro corrompido ou pré-alocar espaço — com exemplos executáveis.

O Que a Função ftruncate() Faz

ftruncate() trunca um arquivo aberto para o tamanho que você especifica, medido em bytes:

• Se o arquivo for maior que length, os bytes extras são descartados.
• Se o arquivo for menor que length, ele é estendido e a nova área é preenchida com bytes nulos (\0).
• Se length for igual a 0, o arquivo é esvaziado — uma forma comum de limpar um arquivo sem excluí-lo.

Retorna true em caso de sucesso e false em caso de falha. É importante notar que ftruncate() não move o ponteiro interno do arquivo. Se você escreveu até o byte 50 e depois truncou para 10 bytes, o ponteiro ainda está em 50, portanto a próxima escrita começará ali e reestenderá o arquivo com bytes nulos. Use rewind() ou fseek() para reposicionar o ponteiro depois.

Sintaxe

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

• $stream — o ponteiro de arquivo retornado por fopen(). O arquivo deve ser aberto em um modo gravável (r+, w, w+, a+, etc.). Abrir com r (somente leitura) faz com que ftruncate() falhe.
• $size — o novo tamanho do arquivo em bytes (um inteiro não negativo).

Como Usar ftruncate()

O padrão é sempre os mesmos três passos:

1. Abra o arquivo em um modo gravável com fopen().
2. Chame ftruncate() com o ponteiro de arquivo e o tamanho desejado.
3. Feche o arquivo com fclose().

O exemplo abaixo escreve uma string conhecida, trunca para 5 bytes e lê o resultado de volta para que você veja exatamente o que sobrevive:

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

A saída é:

Hello

Apenas Hello permanece porque o arquivo foi cortado para 5 bytes. Note a chamada a rewind() — sem ela, fread() começaria no byte 13 (além do final) e não retornaria nada.

Expandindo um Arquivo com Bytes Nulos

Quando $size é maior que o arquivo atual, ftruncate() o estende e preenche a nova região com \0. Isso é útil para pré-alocar um arquivo de tamanho fixo:

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

A saída é:

8 bytes

O arquivo agora tem 8 bytes — o abc original seguido de cinco bytes nulos (\0). A chamada a clearstatcache() é importante porque o PHP armazena em cache o resultado de funções baseadas em stat como filesize() dentro de uma requisição; se você já tinha lido o tamanho do arquivo antes, o valor em cache poderia estar desatualizado após um truncamento.

Casos de Uso Comuns

• Limpar um arquivo no lugar. ftruncate($file, 0) esvazia um arquivo de log ou cache mantendo seu inode, permissões e outros identificadores abertos. Isso é mais seguro do que excluí-lo e recriá-lo.
• Remover um registro final. Leia o arquivo, encontre onde começa a última entrada e trunce para esse deslocamento a fim de removê-la sem reescrever o arquivo inteiro.
• Corrigir um arquivo parcialmente escrito. Se uma escrita foi interrompida, truncar de volta a um tamanho conhecido e válido restaura um estado consistente.
• Pré-alocar espaço. Reserve um arquivo de tamanho fixo com antecedência (por exemplo, um índice binário) antes de preenchê-lo.

Armadilhas

• Identificadores somente leitura falham. Abrir com r e chamar ftruncate() retorna false e emite um aviso. Use r+ se precisar manter o conteúdo existente mas ainda precisar escrever.
• O ponteiro não se move. Sempre use rewind() ou fseek() antes de ler ou acrescentar após um truncamento, ou você pode criar preenchimento inesperado com bytes nulos.
• Cache de stat desatualizado. filesize() e funções similares podem reportar o tamanho antigo logo após o truncamento; chame clearstatcache() para obter o valor atual.
• length está em bytes, não em caracteres. Com texto multi-byte (UTF-8), truncar no meio de um caractere pode corromper o último caractere.

Funções Relacionadas

• fopen() — abrir o arquivo antes de truncar.
• fwrite() — escrever dados no arquivo.
• fread() — ler o conteúdo do arquivo de volta.
• fseek() / rewind() — reposicionar o ponteiro após o truncamento.
• fclose() — fechar o arquivo quando terminar.

Conclusão

ftruncate() é a forma precisa de redimensionar um arquivo aberto em PHP — reduzindo-o ao cortar bytes finais, ou aumentando-o com preenchimento de bytes nulos. As coisas principais a lembrar são que o arquivo deve estar aberto em modo gravável, que a função nunca move o ponteiro de arquivo e que clearstatcache() pode ser necessário para ver o novo tamanho. Usada com fopen(), fwrite() e fclose(), ela lida com tarefas que vão desde a limpeza de logs até o reparo de arquivos parcialmente escritos.

Prática