PHP fstat() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Filesystem

Definition

In PHP, fstat() returns information about an open file, such as its size, permissions and last modified time. It works on a file handle, not on a file name.

The result is an array that holds each value twice, once with a number and once with a name like size or mtime. Most beginners only need the named keys.

Syntax

Call fstat() with the values you need. Start with this line.

PHP
$stat = fstat($fp);
CallWhat it does
fstat($fp)['size']Returns the size of the open file in bytes.
fstat($fp)['mtime']Returns the last modified time as a Unix timestamp.
fstat($fp)['mode']Returns the file type and permission bits as a number.

fstat() is close to stat(), but it uses a file you have already opened. Because it reads from the open handle, it does not use the stat cache, so you do not need clearstatcache().

Library declarations
PHP
fstat(resource $stream): array|false

Parameters

ParameterDescription
streamRequired. A file handle returned by fopen() or a similar function.

Return Value

Return ValueDescription
arrayAn array with keys such as dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize and blocks.
falseReturned when the information cannot be read.

PHP Examples

Example 1 — Read the File Size

Open a small file and ask fstat() how many bytes it holds.

PHP
<?php
$path = sys_get_temp_dir() . '/fstat_demo.txt';
file_put_contents($path, 'Hello World');

$fp = fopen($path, 'r');
$stat = fstat($fp);

echo "Size: ", $stat['size'], " bytes", PHP_EOL;

fclose($fp);
unlink($path);

How It Works

  1. The file contains Hello World, which is 11 characters and so 11 bytes.
  2. fopen() gives back a handle, and fstat() uses that handle to read the file details.
  3. The result is an array, and the size key holds the byte count.
  4. fclose() and unlink() clean up the handle and the temporary file.

Example 2 — Detect an Empty File

Opening a file in write mode empties it. fstat() shows a size of 0, which is a handy check before you decide what to do next.

PHP
<?php
$path = sys_get_temp_dir() . '/fstat_empty.txt';

$fp = fopen($path, 'w');
$stat = fstat($fp);

if ($stat === false) {
    echo "Could not read file details", PHP_EOL;
} else {
    echo "Size: ", $stat['size'], " bytes", PHP_EOL;
    if ($stat['size'] === 0) {
        echo "The file is empty", PHP_EOL;
    }
}

fclose($fp);
unlink($path);

How It Works

  1. fopen() with mode w creates the file or empties it if it already exists.
  2. fstat() returns an array, so the false branch is skipped.
  3. The size is exactly 0, which is the integer 0 and not a string.
  4. Checking === 0 prints a friendly message for empty files.

Example 3 — Check That a Handle Points to a Regular File

The mode value holds the file type in its upper bits. Use a bit mask to tell a regular file from a folder.

PHP
<?php
$path = sys_get_temp_dir() . '/fstat_mode.txt';
file_put_contents($path, 'Hello World');

$fp = fopen($path, 'r');
$stat = fstat($fp);

$isRegular = ($stat['mode'] & 0170000) === 0100000;

echo "Size: ", $stat['size'], " bytes", PHP_EOL;
echo "Regular file: ", $isRegular ? 'yes' : 'no', PHP_EOL;

fclose($fp);
unlink($path);

How It Works

  1. The mode value mixes the file type and the permission bits in one number.
  2. The mask 0170000 keeps only the file type bits, and 0100000 is the value for a regular file.
  3. The comparison gives true because the temporary file is a normal file.
  4. The ternary operator turns the true or false into the words yes or no.

Frequently Asked Questions

It returns details about an open file, such as its size, owner, permissions and timestamps, as an array.
fstat() takes an open file handle, while stat() takes a file name. Use fstat() when the file is already open.
Each value is stored twice, once with an index from 0 to 12 and once with a name like size or mtime. Use the names because they are easier to read.
No. fstat() reads the details from the open handle, so the file stat cache does not affect it.
Use fstat($fp)['size']. It gives the size in bytes without reading the whole file.

Next: fsync()

fsync() forces the changes made to an open file to be written to the physical disk. It was.

fsync() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful