fstat()

What is the fstat() Function?

The fstat() function returns metadata about a file from an already open file handle — its size, owner, permissions, and timestamps. The "f" prefix means it works on a file pointer (a resource returned by fopen()), unlike stat(), which takes a file path.

Reach for fstat() when you already have a stream open (for reading or writing) and want its details without re-opening the file by name. This page covers the syntax, the full structure of the returned array, a runnable example, and the common pitfalls.

Syntax

fstat(resource $stream): array|false

$stream is the file pointer returned by fopen(). On success fstat() returns an associative array; on failure it returns false and emits a warning.

The Array fstat() Returns

fstat() returns an array with 26 entries: each value appears twice — once under a numeric index (0–12) and once under a named key. The named keys are the part you usually use:

Because both forms are present, $info[7] and $info['size'] give the same value. Prefer the named keys — they read better and don't depend on order.

How to Use the fstat() Function

The pattern is always: open a stream, call fstat(), use the data, then close the 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);

Running this prints something like:

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

The size is 18 because "Line one\nLine two\n" is exactly 18 bytes. The timestamps come back as Unix timestamps, so date() turns them into something readable. $info['mode'] & 0777 masks off the file-type bits and leaves only the permission digits.

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

These three functions overlap, so it helps to know when to pick each:

• fstat() — you already have an open handle (e.g. a file you are reading or writing). No extra path lookup is needed.
• stat() — you only have a path and want the same metadata array without opening the file.
• filesize() — you only need the byte count and nothing else; it is the simplest of the three.

Common Gotchas

• Pass a resource, not a string. fstat('file.txt') fails — you must pass the handle from fopen(), not the filename. Use stat() if all you have is a path.
• Stat results are cached. PHP caches file metadata per request. If a file changes mid-script and you read it again, call clearstatcache() first to avoid stale values.
• Some fields are platform-dependent. On Windows, blksize and blocks are reported as -1, and uid/gid are typically 0.
• Always close the handle with fclose() when you're done to free the resource.

Conclusion

fstat() is the right tool when you already hold an open file pointer and need its metadata — size, timestamps, owner, and permissions — without re-opening the file by name. Remember that it returns a 26-element array (numeric and named keys), that the size/mtime fields are the ones you'll reach for most, and that clearstatcache() exists for when results look stale. If you only have a path, use stat() instead.

Practice