lstat()

Cos'è la funzione lstat()?

lstat() raccoglie statistiche (dimensione, timestamp, proprietario, permessi e altro) su un file indicato da $filename. La "l" sta per link: a differenza di stat(), che segue un collegamento simbolico e riporta informazioni sulla destinazione a cui punta, lstat() riporta informazioni sul collegamento stesso.

Questa distinzione è rilevante solo per i collegamenti simbolici. Quando $filename è un file ordinario, lstat() e stat() restituiscono dati identici.

Questa pagina tratta la sintassi, l'array restituito, un esempio eseguibile che lo confronta con stat() e le insidie comuni da tenere a mente.

Sintassi

lstat(string $filename): array|false

• $filename — percorso del file o del collegamento simbolico da esaminare.
• Restituisce un array associativo di statistiche in caso di successo, oppure false in caso di errore (ad esempio, se il percorso non esiste).

Un Esempio Eseguibile

Lo script seguente crea un file reale e un symlink che punta ad esso, quindi esamina entrambi con lstat() e stat() per mostrare la differenza:

<?php

$target = sys_get_temp_dir() . '/lstat_target.txt';
$link   = sys_get_temp_dir() . '/lstat_link';

file_put_contents($target, 'hello');   // 5-byte target file
@unlink($link);
symlink($target, $link);

$linkInfo   = lstat($link);   // the link itself
$targetInfo = stat($link);    // follows the link to the target

echo "Link size (lstat):  {$linkInfo['size']} bytes\n";
echo "Target size (stat): {$targetInfo['size']} bytes\n";
echo "Link modified:      " . date('Y-m-d', $linkInfo['mtime']) . "\n";

unlink($link);
unlink($target);

Output tipico:

Link size (lstat):  65 bytes
Target size (stat): 5 bytes
Link modified:      2026-06-20

La dimensione restituita da lstat() è la lunghezza dei dati del percorso del symlink, non la dimensione del file a cui punta — è esattamente l'informazione che stat() nasconde.

L'Array Restituito

lstat() restituisce la stessa struttura di stat(): un array di 26 elementi in cui ogni valore appare due volte — una volta sotto un indice numerico e una volta sotto una chiave stringa leggibile. Preferire sempre le chiavi con nome per maggiore chiarezza:

Poiché le chiavi con nome e quelle numeriche contengono gli stessi valori, $info['size'] e $info[7] sono intercambiabili — ma la forma con nome è molto più leggibile.

Quando Usare lstat() vs stat()

• Usare stat() quando si è interessati al contenuto del file e si vuole che i link vengano risolti in modo trasparente.
• Usare lstat() quando si verifica il filesystem stesso — ad esempio, per distinguere file reali da symlink, o per rilevare un link pendente la cui destinazione è stata eliminata.

Per verificare se un percorso è un symlink prima di chiamare lstat(), abbinarlo a is_link(). Per leggere dove punta un link, usare readlink(), e per crearne uno, usare symlink().

Insidie Comuni

• Cache stat obsoleta. PHP memorizza nella cache i risultati di stat/lstat per richiesta. Se un file cambia durante l'esecuzione, chiamare clearstatcache(true, $filename) prima di rileggerlo.
• Windows. I collegamenti simbolici esistono su Windows ma richiedono privilegi elevati per essere creati; il comportamento può differire dai sistemi POSIX.
• Permessi. Il processo PHP deve avere accesso in lettura alla directory che contiene il link. Su sistemi sicuri, i moduli di sicurezza (come SELinux o le restrizioni open_basedir) possono bloccare l'accesso anche quando i permessi del file sembrano corretti.

Conclusione

lstat() fornisce i metadati di un collegamento simbolico senza seguirlo — l'unica cosa che stat() non può fare. Usarla ogni volta che si devono esaminare i link stessi anziché le loro destinazioni, leggere i valori tramite le chiavi con nome e verificare sempre un eventuale ritorno false prima di fidarsi del risultato.

Pratica