fstat()

O que é a Função fstat()?

A função fstat() retorna metadados de um arquivo a partir de um handle de arquivo já aberto — seu tamanho, proprietário, permissões e timestamps. O prefixo "f" indica que ela trabalha com um ponteiro de arquivo (um recurso retornado por fopen()), ao contrário de stat(), que recebe um caminho de arquivo.

Use fstat() quando você já tem um stream aberto (para leitura ou escrita) e deseja obter seus detalhes sem reabrir o arquivo pelo nome. Esta página cobre a sintaxe, a estrutura completa do array retornado, um exemplo executável e as armadilhas mais comuns.

Sintaxe

fstat(resource $stream): array|false

$stream é o ponteiro de arquivo retornado por fopen(). Em caso de sucesso, fstat() retorna um array associativo; em caso de falha, retorna false e emite um aviso.

O Array Retornado por fstat()

fstat() retorna um array com 26 entradas: cada valor aparece duas vezes — uma vez sob um índice numérico (0–12) e outra sob uma chave nomeada. As chaves nomeadas são a parte que você geralmente usa:

Como ambas as formas estão presentes, $info[7] e $info['size'] retornam o mesmo valor. Prefira as chaves nomeadas — elas são mais legíveis e não dependem da ordem.

Como Usar a Função fstat()

O padrão é sempre: abrir um stream, chamar fstat(), usar os dados e depois fechar o stream.

<?php

$path = 'example.txt';
file_put_contents($path, "Line one\nLine two\n");

// fstat() needs an open file handle, not a filename.
$handle = fopen($path, 'r');
$info   = fstat($handle);

echo "Size:     " . $info['size'] . " bytes\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";

fclose($handle);

Ao executar, será impresso algo como:

Size:     18 bytes
Modified: 2026-06-21 07:49:12
Permissions: 644

O tamanho é 18 porque "Line one\nLine two\n" tem exatamente 18 bytes. Os timestamps são retornados como timestamps Unix, então date() os converte em algo legível. $info['mode'] & 0777 remove os bits do tipo de arquivo e deixa apenas os dígitos de permissão.

fstat() vs. stat() vs. filesize()

Essas três funções se sobrepõem, por isso é útil saber quando usar cada uma:

• fstat() — quando você já tem um handle aberto (por exemplo, um arquivo que está lendo ou escrevendo). Nenhuma busca extra por caminho é necessária.
• stat() — quando você só tem um caminho e quer o mesmo array de metadados sem abrir o arquivo.
• filesize() — quando você só precisa da contagem de bytes e nada mais; é a mais simples das três.

Armadilhas Comuns

• Passe um recurso, não uma string. fstat('file.txt') falha — você deve passar o handle de fopen(), não o nome do arquivo. Use stat() se tudo que você tem é um caminho.
• Resultados de stat são armazenados em cache. O PHP armazena em cache os metadados de arquivo por requisição. Se um arquivo mudar no meio do script e você o ler novamente, chame clearstatcache() primeiro para evitar valores desatualizados.
• Alguns campos dependem da plataforma. No Windows, blksize e blocks são reportados como -1, e uid/gid são tipicamente 0.
• Sempre feche o handle com fclose() quando terminar para liberar o recurso.

Conclusão

fstat() é a ferramenta certa quando você já tem um ponteiro de arquivo aberto e precisa de seus metadados — tamanho, timestamps, proprietário e permissões — sem reabrir o arquivo pelo nome. Lembre-se de que ela retorna um array de 26 elementos (chaves numéricas e nomeadas), que os campos size/mtime são os que você mais usará, e que clearstatcache() existe para quando os resultados parecerem desatualizados. Se você só tem um caminho, use stat().

Prática