fileinode()

What is the fileinode() Function?

The PHP fileinode() function returns the inode number of a file. An inode (index node) is the identifier the filesystem uses internally to track a file's metadata and data blocks on disk — the actual entry the file's name points to. Two filenames that share the same inode number are hard links to the same physical file, so fileinode() is the standard way to detect that.

This page covers the syntax, the return value, how to handle missing files, the stat cache that affects it, and the practical reasons you'd reach for it.

Syntax

fileinode(string $filename): int|false

• $filename — the path to the file you want to inspect.
• Return value — the inode number as an integer on success, or false on failure (for example, when the file does not exist). On most 64-bit systems the value is a large integer.

Basic Example

The example below uses __FILE__ (the magic constant for the path of the currently running script) so it always points at a file that really exists:

<?php

$filename = __FILE__;
$inode = fileinode($filename);

echo "The inode number of $filename is $inode";

Output (the exact number depends on your filesystem):

The inode number of /path/to/script.php is 326428208

We pass the path to fileinode(), store the returned integer in $inode, and print it.

Handling Failure

When the file doesn't exist (or isn't accessible), fileinode() returns false and emits an E_WARNING. Use strict comparison (===) so a legitimate inode of 0 is never mistaken for failure:

<?php

$filename = 'does-not-exist.txt';
$inode = @fileinode($filename); // @ suppresses the warning

if ($inode === false) {
    echo "Could not read the inode for $filename — it may not exist.";
} else {
    echo "Inode: $inode";
}

Output:

Could not read the inode for does-not-exist.txt — it may not exist.

A safer pattern is to check existence first with file_exists() rather than suppressing warnings.

Detecting Hard Links

The most common real-world use of fileinode() is comparing two paths: if they report the same inode number on the same filesystem, they are the same file accessed through different names.

<?php

$a = fileinode('/path/to/original.txt');
$b = fileinode('/path/to/hardlink.txt');

if ($a !== false && $a === $b) {
    echo "Both names point to the same file (hard link).";
} else {
    echo "These are distinct files.";
}

The Stat Cache

PHP caches the result of filesystem stat calls (fileinode(), filesize(), filemtime(), and friends) for performance. If a file is replaced or relinked while your script runs, you may get a stale inode. Call clearstatcache() to force PHP to read fresh metadata:

<?php

$first = fileinode(__FILE__);
clearstatcache();            // discard cached stat data
$second = fileinode(__FILE__);

var_dump($first === $second); // bool(true) — unchanged file

When Would I Use It?

• Deduplication — group files that are hard links to the same data instead of copying them.
• Detecting renames vs. new files — a changed name with the same inode is a rename, not a fresh file.
• Diagnostics and tooling — pairs naturally with the other stat functions when auditing a directory.

For the full set of metadata at once, see stat(). For specific attributes there are dedicated functions: filesize(), filemtime(), fileatime(), filetype(), and fileperms().

Conclusion

fileinode() returns the filesystem inode number of a file as an integer, or false on failure. Beyond simply reading the number, its real value is identifying when two paths refer to the same underlying file. Always compare with ===, guard against missing files, and call clearstatcache() when a file may have changed mid-script.

Practice