linkinfo()

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

A função linkinfo() é uma função nativa do PHP que verifica se um link realmente existe e, em sistemas Unix, retorna o dispositivo no qual ele reside. Especificamente, ela retorna o campo st_dev da estrutura C stat produzida pela chamada de sistema lstat() — um inteiro que identifica o dispositivo (disco/partição) que contém o link.

Na prática, linkinfo() é mais útil como uma verificação rápida de existência: se retornar 0 ou um inteiro positivo, o link existe; se retornar -1 ou false, o caminho está ausente, quebrado ou inacessível. Apesar do nome, ela não retorna o número de hard links — essa informação vem do elemento nlink de stat() ou lstat().

Esta página aborda a sintaxe da função, valores de retorno, um exemplo executável, armadilhas comuns e funções relacionadas ao sistema de arquivos.

Sintaxe

linkinfo(string $path): int|false

A função aceita um único parâmetro:

• $path — o caminho para o link simbólico ou hard link que você deseja inspecionar.

Ela retorna:

• um inteiro não negativo (o identificador de dispositivo st_dev) quando o link existe,
• -1 quando o link não pode ser lido, mas lstat tem sucesso parcial, ou
• false se $path não existe ou não pode ser acessado.

Como 0 é um valor de retorno válido que pode ser interpretado como falso em algumas plataformas, sempre compare com !== false em vez de depender de um teste booleano solto.

Como Usar a Função linkinfo()

Siga estes passos:

1. Especifique o caminho para o link simbólico ou hard link que deseja verificar.
2. Chame linkinfo(), passando o caminho.
3. Compare o resultado estritamente contra false para determinar se o link existe.

O exemplo abaixo cria um arquivo real e um link simbólico para ele, depois inspeciona o link com linkinfo():

<?php

// Set up a file and a symbolic link to it in the temp directory.
$target = tempnam(sys_get_temp_dir(), 'tgt');
$link   = sys_get_temp_dir() . '/example_link';

@unlink($link);            // remove a leftover link from a previous run
symlink($target, $link);   // create the symlink

$info = linkinfo($link);

if ($info !== false) {
    echo "The link '$link' exists. Device id (st_dev): $info" . PHP_EOL;
} else {
    echo "The link '$link' does not exist or is inaccessible." . PHP_EOL;
}

// A path that doesn't exist fails: false on most systems, -1 on some
// Unix builds (a warning may also be emitted), so treat both as "missing".
$missing = @linkinfo('/no/such/link');
var_dump($missing === false || $missing === -1); // bool(true) -> "missing"

// Clean up.
unlink($link);
unlink($target);

Uma execução típica imprime algo como:

The link '/tmp/example_link' exists. Device id (st_dev): 16777220
bool(true)

O identificador de dispositivo exato depende do seu sistema operacional e sistema de arquivos, portanto não o codifique diretamente — apenas sua presença é significativa. Para o caminho ausente, o PHP retorna false na maioria das plataformas e -1 em algumas compilações Unix, razão pela qual o exemplo trata ambos como "não encontrado."

Armadilhas Comuns

• Windows. linkinfo() não é significativa no Windows e efetivamente apenas informa se o caminho é um link. Utilize-a para verificação de existência, não para o número do dispositivo.
• Use !== false, não !$info. Em alguns sistemas, um link válido retorna 0, que uma verificação solta trataria como "ausente."
• Ela não segue o link. linkinfo() inspeciona o próprio link (como lstat), não o arquivo para o qual o link aponta. Um symlink para um alvo excluído ainda será reportado como existente.
• Não serve para contar hard links. Use stat($path)['nlink'] se precisar da contagem de hard links.

Funções Relacionadas

• symlink() — cria um link simbólico.
• link() — cria um hard link.
• readlink() — retorna o alvo para o qual um link simbólico aponta.
• is_link() — testa se um caminho é um link simbólico.
• lstat() — informações completas de status para um link sem segui-lo.

Conclusão

A função linkinfo() é uma maneira leve de confirmar que um link existe e de ler o dispositivo no qual ele reside, espelhando o campo st_dev de lstat(). Use-a para verificações de existência (sempre com uma comparação estrita !== false), e recorra a stat() ou is_link() quando precisar de detalhes mais ricos, como a contagem de hard links ou o tipo de link.

Prática