lstat()

Was ist die lstat()-Funktion?

lstat() erfasst Statistiken (Größe, Zeitstempel, Eigentümer, Berechtigungen und mehr) über eine Datei, die durch $filename angegeben wird. Das „l" steht für link (Verknüpfung): Im Gegensatz zu stat(), das einem symbolischen Link folgt und Informationen über das Ziel liefert, gibt lstat() Informationen über den Link selbst zurück.

Dieser Unterschied ist nur bei symbolischen Links relevant. Wenn $filename eine gewöhnliche Datei ist, liefern lstat() und stat() identische Daten.

Diese Seite behandelt die Syntax, das zurückgegebene Array, ein ausführbares Beispiel, das den Unterschied zu stat() verdeutlicht, sowie häufige Fallstricke.

Syntax

lstat(string $filename): array|false

• $filename — Pfad zur Datei oder zum symbolischen Link, der untersucht werden soll.
• Gibt zurück: ein assoziatives Array mit Statistiken bei Erfolg oder false bei einem Fehler (zum Beispiel, wenn der Pfad nicht existiert).

Ein ausführbares Beispiel

Das folgende Skript erstellt eine echte Datei und einen Symlink, der auf sie zeigt, und untersucht dann beide mit lstat() und stat(), sodass Sie den Unterschied erkennen können:

<?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);

Typische Ausgabe:

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

Die von lstat() zurückgegebene Größe entspricht der Länge der Pfaddaten des Symlinks, nicht der Größe der Datei, auf die er zeigt — genau das sind die Informationen, die stat() vor Ihnen verbergen würde.

Das zurückgegebene Array

lstat() gibt dieselbe Struktur wie stat() zurück: ein 26-Element-Array, in dem jeder Wert zweimal erscheint — einmal unter einem numerischen Index und einmal unter einem lesbaren String-Schlüssel. Verwenden Sie für die Übersichtlichkeit stets die benannten Schlüssel:

Da die benannten und numerischen Schlüssel dieselben Werte enthalten, sind $info['size'] und $info[7] austauschbar — die benannte Form ist jedoch deutlich leichter lesbar.

Wann lstat() vs. stat() verwenden?

• Verwenden Sie stat(), wenn Sie sich für den Inhalt der Datei interessieren und Links transparent aufgelöst werden sollen.
• Verwenden Sie lstat(), wenn Sie das Dateisystem selbst analysieren — zum Beispiel um echte Dateien von Symlinks zu unterscheiden oder einen hängenden Link zu erkennen, dessen Ziel gelöscht wurde.

Um zu prüfen, ob ein Pfad ein Symlink ist, bevor Sie lstat() aufrufen, kombinieren Sie es mit is_link(). Um zu lesen, wohin ein Link zeigt, verwenden Sie readlink(), und um einen zu erstellen, verwenden Sie symlink().

Fallstricke

• Veralteter Stat-Cache. PHP speichert stat-/lstat-Ergebnisse pro Anfrage im Cache. Wenn sich eine Datei während der Ausführung ändert, rufen Sie clearstatcache(true, $filename) auf, bevor Sie sie erneut lesen.
• Windows. Symbolische Links existieren unter Windows, erfordern jedoch erhöhte Rechte zur Erstellung; das Verhalten kann sich von POSIX-Systemen unterscheiden.
• Berechtigungen. Ihr PHP-Prozess benötigt Lesezugriff auf das Verzeichnis, das den Link enthält. Auf abgesicherten Systemen können Sicherheitsmodule (wie SELinux oder open_basedir-Einschränkungen) den Zugriff blockieren, selbst wenn die Dateirechte korrekt aussehen.

Fazit

lstat() liefert die Metadaten eines symbolischen Links, ohne ihm zu folgen — das Einzige, was stat() nicht kann. Greifen Sie darauf zurück, wenn Sie Links selbst statt ihrer Ziele untersuchen müssen, lesen Sie Werte über ihre benannten Schlüssel aus, und prüfen Sie stets auf einen false-Rückgabewert, bevor Sie dem Ergebnis vertrauen.

Übung