eio_statvfs — Funktion · PHP-Referenz

Signatur

eio_statvfs(string $path, int $pri, callable $callback, mixed $data = null): resource|false

Beschreibung

eio_statvfs() ermittelt asynchron Informationen über das Dateisystem, in dem sich der übergebene Pfad befindet. Die Funktion arbeitet nicht-blockierend: Sie gibt sofort eine Ressource zurück und ruft $callback auf, sobald das Betriebssystem die Statistiken bereitgestellt hat.

Im Callback erhält man ein assoziatives Array mit Schlüsseln wie f_bsize (Blockgröße), f_blocks (Gesamtblöcke), f_bfree (freie Blöcke), f_bavail (für Nicht-Root verfügbare Blöcke), f_files (Inode-Gesamtanzahl), f_ffree (freie Inodes) und weitere posix-konforme Felder. Dies entspricht dem POSIX-Systemaufruf statvfs(3).

Typische Einsatzgebiete sind Monitoring-Anwendungen, Upload-Services oder Deployment-Werkzeuge, die den verfügbaren Festplattenspeicher prüfen müssen, ohne den Haupt-Prozess zu blockieren. Die Funktion ist Teil der eio-Erweiterung und erfordert eine laufende Event-Loop (z. B. eio_event_loop()).

Der Prioritätsparameter $pri steuert die Reihenfolge, in der ausstehende asynchrone I/O-Anfragen abgearbeitet werden. In den meisten Fällen genügt EIO_PRI_DEFAULT.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Pfad zu einer Datei oder einem Verzeichnis auf dem zu untersuchenden Dateisystem. Der Pfad muss für den laufenden Prozess zugänglich sein.
$pri Pflicht	int		Priorität der Anfrage. Verwende eine der Konstanten `EIO_PRI_DEFAULT`, `EIO_PRI_MIN` oder `EIO_PRI_MAX`. `EIO_PRI_DEFAULT` ist für die meisten Fälle ausreichend.
$callback Pflicht	callable		Wird nach Abschluss der Operation aufgerufen. Signatur: `function(mixed $data, int $result, resource $req): void`. `$result` enthält das assoziative Array mit den Dateisystem-Statistiken oder `-1` im Fehlerfall.
$data	mixed	null	Beliebige benutzerdefinierte Daten, die unverändert als erstes Argument an `$callback` weitergereicht werden. Nützlich, um Kontextobjekte oder Identifikatoren mitzuführen.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt bei Erfolg eine eio-Anfrage-Ressource zurück, mit der die Anfrage z. B. über eio_cancel() abgebrochen werden kann. Im Fehlerfall wird false zurückgegeben.

Beispiele

Freien Speicherplatz eines Dateisystems ermitteln

<?php
// eio-Erweiterung muss geladen sein

eio_statvfs(
    '/',
    EIO_PRI_DEFAULT,
    function (mixed $data, mixed $result, $req): void {
        if (!is_array($result)) {
            echo "Fehler: Statistiken konnten nicht gelesen werden.\n";
            return;
        }

        $blockSize  = $result['f_frsize'];   // Fragmentgröße in Byte
        $freeBlocks = $result['f_bavail'];   // Für Nicht-Root freie Blöcke
        $freeMiB    = ($blockSize * $freeBlocks) / 1024 / 1024;

        printf(
            "Dateisystem: %s\nFreier Speicher: %.2f MiB\n",
            $data,
            $freeMiB
        );
    },
    '/'
);

eio_event_loop();

Dateisystem: / Freier Speicher: 45678.90 MiB

Inode-Auslastung prüfen

<?php
$path = '/var/www';

eio_statvfs(
    $path,
    EIO_PRI_DEFAULT,
    function (mixed $data, mixed $result, $req): void {
        if (!is_array($result)) {
            echo "Fehler beim Lesen der Inode-Statistiken.\n";
            return;
        }

        $totalInodes = $result['f_files'];
        $freeInodes  = $result['f_ffree'];
        $usedPercent = $totalInodes > 0
            ? round((($totalInodes - $freeInodes) / $totalInodes) * 100, 1)
            : 0;

        printf(
            "Pfad: %s\nInodes gesamt: %d | frei: %d | Auslastung: %.1f%%\n",
            $data,
            $totalInodes,
            $freeInodes,
            $usedPercent
        );

        if ($usedPercent > 90) {
            echo "WARNUNG: Inode-Auslastung kritisch!\n";
        }
    },
    $path
);

eio_event_loop();

Pfad: /var/www Inodes gesamt: 1310720 | frei: 987456 | Auslastung: 24.6%

// Wichtig · Fallstricke

Verfügbarkeit: eio_statvfs() steht nur zur Verfügung, wenn die eio-PECL-Erweiterung installiert ist. Sie ist nicht Bestandteil des PHP-Kerns.

Event-Loop: Ohne Aufruf von eio_event_loop() (oder einer alternativen Loop-Integration wie ReactPHP/libeio) wird der Callback nie ausgeführt. Stelle sicher, dass die Loop läuft, bevor du auf Ergebnisse wartest.

Fehlerbehandlung: Prüfe im Callback, ob $result ein Array ist. Bei Fehlern (z. B. unbekannter Pfad, fehlende Rechte) wird -1 oder null übergeben. Mit eio_get_last_error($req) kann die Fehlerursache abgefragt werden.

Plattformabhängigkeit: Nicht alle Felder des zurückgegebenen Arrays sind auf jedem Betriebssystem aussagekräftig gefüllt. Insbesondere unter Windows kann die Verfügbarkeit eingeschränkt sein.

Siehe auch

eio_event_loop eio_cancel eio_stat eio_lstat disk_free_space disk_total_space