fileinode()

O que é a Função fileinode()?

A função PHP fileinode() retorna o número de inode de um arquivo. Um inode (nó de índice) é o identificador que o sistema de arquivos usa internamente para rastrear os metadados e os blocos de dados de um arquivo no disco — a entrada real para a qual o nome do arquivo aponta. Dois nomes de arquivo que compartilham o mesmo número de inode são hard links para o mesmo arquivo físico, portanto fileinode() é a forma padrão de detectar isso.

Esta página aborda a sintaxe, o valor de retorno, como lidar com arquivos ausentes, o cache de stat que o afeta e as razões práticas pelas quais você o utilizaria.

Sintaxe

fileinode(string $filename): int|false

• $filename — o caminho para o arquivo que você deseja inspecionar.
• Valor de retorno — o número de inode como um inteiro em caso de sucesso, ou false em caso de falha (por exemplo, quando o arquivo não existe). Na maioria dos sistemas de 64 bits, o valor é um inteiro grande.

Exemplo Básico

O exemplo abaixo usa __FILE__ (a constante mágica para o caminho do script em execução atual) para que sempre aponte para um arquivo que realmente existe:

<?php

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

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

Saída (o número exato depende do seu sistema de arquivos):

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

Passamos o caminho para fileinode(), armazenamos o inteiro retornado em $inode e o imprimimos.

Tratando Falhas

Quando o arquivo não existe (ou não está acessível), fileinode() retorna false e emite um E_WARNING. Use comparação estrita (===) para que um inode legítimo de 0 nunca seja confundido com falha:

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

Saída:

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

Um padrão mais seguro é verificar a existência primeiro com file_exists() em vez de suprimir avisos.

Detectando Hard Links

O uso mais comum no mundo real de fileinode() é comparar dois caminhos: se eles reportarem o mesmo número de inode no mesmo sistema de arquivos, eles são o mesmo arquivo acessado por nomes 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.";
}

O Cache de Stat

O PHP armazena em cache o resultado das chamadas de stat do sistema de arquivos (fileinode(), filesize(), filemtime() e similares) por questão de desempenho. Se um arquivo for substituído ou vinculado novamente enquanto seu script é executado, você pode obter um inode desatualizado. Chame clearstatcache() para forçar o PHP a ler metadados atualizados:

<?php

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

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

Quando Devo Usá-la?

• Deduplicação — agrupe arquivos que são hard links para os mesmos dados em vez de copiá-los.
• Detectar renomeações vs. novos arquivos — um nome alterado com o mesmo inode é uma renomeação, não um arquivo novo.
• Diagnóstico e ferramentas — combina naturalmente com as outras funções stat ao auditar um diretório.

Para o conjunto completo de metadados de uma vez, consulte stat(). Para atributos específicos, existem funções dedicadas: filesize(), filemtime(), fileatime(), filetype() e fileperms().

Conclusão

fileinode() retorna o número de inode do sistema de arquivos de um arquivo como um inteiro, ou false em caso de falha. Além de simplesmente ler o número, seu valor real está em identificar quando dois caminhos se referem ao mesmo arquivo subjacente. Sempre compare com ===, proteja-se contra arquivos ausentes e chame clearstatcache() quando um arquivo puder ter mudado durante a execução do script.

Prática