fileinode()

¿Qué es la función fileinode()?

La función PHP fileinode() devuelve el número de inodo de un archivo. Un inodo (nodo índice) es el identificador que el sistema de archivos utiliza internamente para rastrear los metadatos y los bloques de datos de un archivo en disco — la entrada real a la que apunta el nombre del archivo. Dos nombres de archivo que comparten el mismo número de inodo son enlaces duros al mismo archivo físico, por lo que fileinode() es la forma estándar de detectarlo.

Esta página cubre la sintaxis, el valor de retorno, cómo manejar archivos inexistentes, la caché de stat que lo afecta y las razones prácticas por las que lo usarías.

Sintaxis

fileinode(string $filename): int|false

• $filename — la ruta al archivo que deseas inspeccionar.
• Valor de retorno — el número de inodo como un entero en caso de éxito, o false en caso de error (por ejemplo, cuando el archivo no existe). En la mayoría de los sistemas de 64 bits, el valor es un entero grande.

Ejemplo básico

El siguiente ejemplo usa __FILE__ (la constante mágica para la ruta del script que se está ejecutando actualmente) para que siempre apunte a un archivo que realmente existe:

<?php

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

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

Salida (el número exacto depende de tu sistema de archivos):

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

Pasamos la ruta a fileinode(), almacenamos el entero devuelto en $inode y lo imprimimos.

Manejo de errores

Cuando el archivo no existe (o no es accesible), fileinode() devuelve false y emite un E_WARNING. Usa comparación estricta (===) para que un inodo legítimo con valor 0 nunca se confunda con un error:

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

Salida:

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

Un patrón más seguro es verificar primero la existencia con file_exists() en lugar de suprimir las advertencias.

Detección de enlaces duros

El uso más común de fileinode() en el mundo real es comparar dos rutas: si reportan el mismo número de inodo en el mismo sistema de archivos, son el mismo archivo accedido a través de nombres diferentes.

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

La caché de stat

PHP almacena en caché el resultado de las llamadas stat al sistema de archivos (fileinode(), filesize(), filemtime() y similares) por razones de rendimiento. Si un archivo es reemplazado o revinculado mientras se ejecuta tu script, es posible que obtengas un inodo desactualizado. Llama a clearstatcache() para forzar a PHP a leer metadatos actualizados:

<?php

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

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

¿Cuándo lo usaría?

• Deduplicación — agrupa archivos que son enlaces duros a los mismos datos en lugar de copiarlos.
• Detección de renombrados vs. archivos nuevos — un nombre cambiado con el mismo inodo es un renombrado, no un archivo nuevo.
• Diagnóstico y herramientas — se combina de forma natural con las otras funciones stat al auditar un directorio.

Para el conjunto completo de metadatos de una vez, consulta stat(). Para atributos específicos existen funciones dedicadas: filesize(), filemtime(), fileatime(), filetype() y fileperms().

Conclusión

fileinode() devuelve el número de inodo del sistema de archivos de un archivo como entero, o false en caso de error. Más allá de simplemente leer el número, su valor real está en identificar cuándo dos rutas hacen referencia al mismo archivo subyacente. Siempre compara con ===, protégete contra archivos inexistentes y llama a clearstatcache() cuando un archivo puede haber cambiado durante la ejecución del script.

Práctica