fstat()

Что такое функция fstat()?

Функция fstat() возвращает метаданные о файле через уже открытый файловый дескриптор — его размер, владельца, права доступа и временные метки. Префикс «f» означает, что функция работает с файловым указателем (ресурсом, возвращаемым fopen()), в отличие от stat(), которая принимает путь к файлу.

Используйте fstat(), когда у вас уже открыт поток (для чтения или записи) и нужно получить информацию о файле без повторного его открытия по имени. На этой странице рассмотрены синтаксис, полная структура возвращаемого array, рабочий пример и распространённые ловушки.

Синтаксис

fstat(resource $stream): array|false

$stream — файловый указатель, возвращённый функцией fopen(). В случае успеха fstat() возвращает ассоциативный array; при ошибке возвращает false и выдаёт предупреждение.

Array, возвращаемый fstat()

fstat() возвращает array из 26 элементов: каждое значение присутствует дважды — под числовым индексом (0–12) и под именованным ключом. Именованные ключи — это то, с чем вы обычно работаете:

Поскольку обе формы присутствуют, $info[7] и $info['size'] дают одно и то же значение. Предпочтительнее использовать именованные ключи — они лучше читаются и не зависят от порядка.

Как использовать функцию fstat()

Шаблон всегда один: открыть поток, вызвать fstat(), использовать данные, затем закрыть поток.

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

При запуске будет выведено примерно следующее:

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

Размер равен 18, потому что "Line one\nLine two\n" занимает ровно 18 байт. Временные метки возвращаются как Unix-временные метки, поэтому date() преобразует их в читаемый формат. $info['mode'] & 0777 маскирует биты типа файла, оставляя только цифры прав доступа.

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

Эти три функции частично перекрываются, поэтому полезно знать, когда какую выбирать:

• fstat() — когда у вас уже есть открытый дескриптор (например, файл, который вы читаете или пишете). Дополнительный поиск по пути не требуется.
• stat() — когда у вас есть только путь и вы хотите получить тот же ассоциативный array метаданных без открытия файла.
• filesize() — когда нужен только размер в байтах и ничего больше; это самая простая из трёх функций.

Распространённые ловушки

• Передавайте ресурс, а не string. fstat('file.txt') завершится ошибкой — нужно передать дескриптор от fopen(), а не имя файла. Используйте stat(), если у вас есть только путь.
• Результаты stat кэшируются. PHP кэширует метаданные файлов в рамках одного запроса. Если файл изменился в середине выполнения скрипта и вы снова его читаете, предварительно вызовите clearstatcache(), чтобы избежать устаревших значений.
• Некоторые поля зависят от платформы. В Windows blksize и blocks сообщаются как -1, а uid/gid обычно равны 0.
• Всегда закрывайте дескриптор с помощью fclose() по завершении работы, чтобы освободить ресурс.

Заключение

fstat() — правильный инструмент, когда у вас уже есть открытый файловый указатель и нужны его метаданные — размер, временные метки, владелец и права доступа — без повторного открытия файла по имени. Помните, что функция возвращает array из 26 элементов (числовые и именованные ключи), что поля size/mtime вы будете использовать чаще всего, и что clearstatcache() существует для случаев, когда результаты выглядят устаревшими. Если у вас есть только путь, используйте stat().

Практика