fstat()

¿Qué es la función fstat()?

La función fstat() devuelve metadatos sobre un archivo a partir de un identificador de archivo ya abierto — su tamaño, propietario, permisos y marcas de tiempo. El prefijo "f" indica que trabaja con un puntero de archivo (un recurso devuelto por fopen()), a diferencia de stat(), que recibe una ruta de archivo.

Utiliza fstat() cuando ya tienes un flujo abierto (para lectura o escritura) y necesitas sus detalles sin volver a abrir el archivo por nombre. Esta página cubre la sintaxis, la estructura completa del array devuelto, un ejemplo ejecutable y los errores más comunes.

Sintaxis

fstat(resource $stream): array|false

$stream es el puntero de archivo devuelto por fopen(). Si la operación tiene éxito, fstat() devuelve un array asociativo; en caso de fallo devuelve false y emite una advertencia.

El array que devuelve fstat()

fstat() devuelve un array con 26 entradas: cada valor aparece dos veces — una bajo un índice numérico (0–12) y otra bajo una clave con nombre. Las claves con nombre son las que normalmente se usan:

Como ambas formas están presentes, $info[7] e $info['size'] devuelven el mismo valor. Prefiere las claves con nombre — son más legibles y no dependen del orden.

Cómo usar la función fstat()

El patrón es siempre el mismo: abre un flujo, llama a fstat(), usa los datos y cierra el flujo.

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

Al ejecutarlo se muestra algo similar a:

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

El tamaño es 18 porque "Line one\nLine two\n" ocupa exactamente 18 bytes. Las marcas de tiempo se devuelven como marcas de tiempo Unix, por lo que date() las convierte en algo legible. $info['mode'] & 0777 enmascara los bits de tipo de archivo y deja solo los dígitos de permisos.

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

Estas tres funciones se solapan, por lo que conviene saber cuándo elegir cada una:

• fstat() — ya tienes un identificador abierto (p. ej., un archivo que estás leyendo o escribiendo). No es necesaria ninguna búsqueda adicional por ruta.
• stat() — solo tienes una ruta y quieres el mismo array de metadatos sin abrir el archivo.
• filesize() — solo necesitas el número de bytes y nada más; es la más sencilla de las tres.

Errores comunes

• Pasa un recurso, no una cadena. fstat('file.txt') falla — debes pasar el identificador de fopen(), no el nombre del archivo. Usa stat() si solo tienes una ruta.
• Los resultados de stat se almacenan en caché. PHP almacena en caché los metadatos de los archivos por petición. Si un archivo cambia durante la ejecución del script y lo lees de nuevo, llama primero a clearstatcache() para evitar valores obsoletos.
• Algunos campos dependen de la plataforma. En Windows, blksize y blocks se reportan como -1, y uid/gid suelen ser 0.
• Cierra siempre el identificador con fclose() cuando termines para liberar el recurso.

Conclusión

fstat() es la herramienta adecuada cuando ya tienes un puntero de archivo abierto y necesitas sus metadatos — tamaño, marcas de tiempo, propietario y permisos — sin volver a abrir el archivo por nombre. Recuerda que devuelve un array de 26 elementos (claves numéricas y con nombre), que los campos size/mtime son los que usarás con más frecuencia, y que clearstatcache() existe para cuando los resultados parecen obsoletos. Si solo tienes una ruta, usa stat() en su lugar.

Práctica