fstat()

Was ist die Funktion fstat()?

Die Funktion fstat() gibt Metadaten über eine Datei aus einem bereits geöffneten Datei-Handle zurück — Größe, Eigentümer, Berechtigungen und Zeitstempel. Das Präfix „f" bedeutet, dass sie mit einem Datei-Zeiger (einer Ressource, die von fopen() zurückgegeben wird) arbeitet, im Gegensatz zu stat(), das einen Datei-Pfad entgegennimmt.

Verwenden Sie fstat(), wenn Sie bereits einen Stream geöffnet haben (zum Lesen oder Schreiben) und dessen Details benötigen, ohne die Datei erneut über den Namen öffnen zu müssen. Diese Seite behandelt die Syntax, die vollständige Struktur des zurückgegebenen Arrays, ein ausführbares Beispiel und häufige Fallstricke.

Syntax

fstat(resource $stream): array|false

$stream ist der Datei-Zeiger, der von fopen() zurückgegeben wird. Bei Erfolg gibt fstat() ein assoziatives array zurück; bei einem Fehler gibt es false zurück und gibt eine Warnung aus.

Das von fstat() zurückgegebene Array

fstat() gibt ein array mit 26 Einträgen zurück: Jeder Wert erscheint zweimal — einmal unter einem numerischen Index (0–12) und einmal unter einem benannten Schlüssel. Die benannten Schlüssel sind die, die Sie normalerweise verwenden:

Da beide Formen vorhanden sind, liefern $info[7] und $info['size'] denselben Wert. Bevorzugen Sie die benannten Schlüssel — sie sind besser lesbar und hängen nicht von der Reihenfolge ab.

Verwendung der Funktion fstat()

Das Muster ist immer: einen Stream öffnen, fstat() aufrufen, die Daten verwenden und dann den Stream schließen.

<?php

$path = 'example.txt';
file_put_contents($path, "Line one\nLine two\n");

// fstat() needs an open file handle, not a filename.
$handle = fopen($path, 'r');
$info   = fstat($handle);

echo "Size:     " . $info['size'] . " bytes\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";

fclose($handle);

Die Ausführung gibt etwa Folgendes aus:

Size:     18 bytes
Modified: 2026-06-21 07:49:12
Permissions: 644

Die Größe ist 18, weil "Line one\nLine two\n" genau 18 Bytes umfasst. Die Zeitstempel werden als Unix-Zeitstempel zurückgegeben, daher konvertiert date() sie in ein lesbares Format. $info['mode'] & 0777 maskiert die Dateityp-Bits und lässt nur die Berechtigungs-Ziffern übrig.

fstat() vs. stat() vs. filesize()

Diese drei Funktionen überschneiden sich, daher ist es hilfreich zu wissen, wann welche zu verwenden ist:

• fstat() — Sie haben bereits ein geöffnetes Handle (z. B. eine Datei, die Sie lesen oder schreiben). Kein zusätzlicher Pfad-Lookup erforderlich.
• stat() — Sie haben nur einen Pfad und möchten dasselbe Metadaten-Array erhalten, ohne die Datei zu öffnen.
• filesize() — Sie benötigen nur die Byte-Anzahl und sonst nichts; sie ist die einfachste der drei.

Häufige Fallstricke

• Übergeben Sie eine Ressource, keine Zeichenkette. fstat('file.txt') schlägt fehl — Sie müssen das Handle von fopen() übergeben, nicht den Dateinamen. Verwenden Sie stat(), wenn Sie nur einen Pfad haben.
• Stat-Ergebnisse werden zwischengespeichert. PHP speichert Datei-Metadaten pro Anfrage. Wenn sich eine Datei mitten im Skript ändert und Sie sie erneut lesen, rufen Sie zuerst clearstatcache() auf, um veraltete Werte zu vermeiden.
• Einige Felder sind plattformabhängig. Unter Windows werden blksize und blocks als -1 gemeldet, und uid/gid sind typischerweise 0.
• Schließen Sie das Handle immer mit fclose(), wenn Sie fertig sind, um die Ressource freizugeben.

Fazit

fstat() ist das richtige Werkzeug, wenn Sie bereits einen geöffneten Datei-Zeiger halten und dessen Metadaten benötigen — Größe, Zeitstempel, Eigentümer und Berechtigungen — ohne die Datei erneut über den Namen zu öffnen. Denken Sie daran, dass es ein array mit 26 Elementen zurückgibt (numerische und benannte Schlüssel), dass die Felder size/mtime die am häufigsten genutzten sind, und dass clearstatcache() vorhanden ist, wenn Ergebnisse veraltet wirken. Wenn Sie nur einen Pfad haben, verwenden Sie stattdessen stat().

Übungen