fileinode()

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

Функция PHP fileinode() возвращает номер inode файла. Inode (индексный узел) — это идентификатор, который файловая система использует внутренне для отслеживания метаданных файла и блоков данных на диске — это и есть реальная запись, на которую указывает имя файла. Два имени файла, имеющие одинаковый номер inode, являются жёсткими ссылками на один и тот же физический файл, поэтому fileinode() — это стандартный способ обнаружить это.

На этой странице описаны синтаксис, возвращаемое значение, обработка отсутствующих файлов, кэш stat, влияющий на работу функции, и практические причины её использования.

Синтаксис

fileinode(string $filename): int|false

• $filename — путь к файлу, который нужно проверить.
• Возвращаемое значение — номер inode в виде целого числа при успехе, или false при ошибке (например, если файл не существует). На большинстве 64-битных систем значение является большим целым числом.

Базовый пример

В примере ниже используется __FILE__ (магическая константа, содержащая путь к выполняемому скрипту), поэтому она всегда указывает на реально существующий файл:

<?php

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

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

Вывод (точное число зависит от вашей файловой системы):

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

Мы передаём путь в fileinode(), сохраняем возвращённое целое число в $inode и выводим его.

Обработка ошибок

Если файл не существует (или к нему нет доступа), fileinode() возвращает false и генерирует предупреждение E_WARNING. Используйте строгое сравнение (===), чтобы допустимый inode со значением 0 не был ошибочно принят за сбой:

<?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";
}

Вывод:

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

Более безопасный подход — сначала проверять существование файла с помощью file_exists(), а не подавлять предупреждения.

Обнаружение жёстких ссылок

Наиболее распространённое практическое применение fileinode() — сравнение двух путей: если они возвращают одинаковый номер inode в одной и той же файловой системе, значит это один и тот же файл, доступный под разными именами.

<?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.";
}

Кэш stat

PHP кэширует результаты системных вызовов stat (fileinode(), filesize(), filemtime() и других) для повышения производительности. Если файл заменяется или переназначается во время выполнения скрипта, вы можете получить устаревший inode. Вызовите clearstatcache(), чтобы принудить PHP читать актуальные метаданные:

<?php

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

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

Когда это стоит использовать?

• Дедупликация — группировка файлов, являющихся жёсткими ссылками на одни и те же данные, вместо их копирования.
• Обнаружение переименований в отличие от новых файлов — изменённое имя с тем же inode означает переименование, а не новый файл.
• Диагностика и инструменты — хорошо сочетается с другими функциями stat при аудите директории.

Для получения полного набора метаданных одновременно смотрите stat(). Для конкретных атрибутов существуют специализированные функции: filesize(), filemtime(), fileatime(), filetype() и fileperms().

Заключение

fileinode() возвращает номер inode файловой системы в виде целого числа, или false при ошибке. Помимо простого считывания номера, основная ценность функции — определение того, ссылаются ли два пути на один и тот же файл. Всегда используйте сравнение с ===, защищайтесь от отсутствующих файлов и вызывайте clearstatcache(), если файл мог измениться в ходе выполнения скрипта.

Практика