inotify_read — Funktion · PHP-Referenz

Signatur

inotify_read(resource $inotify_instance): array|false

Beschreibung

inotify_read() liest ausstehende Ereignisse von einer mit inotify_init() erstellten Inotify-Instanz. Inotify ist ein Linux-Kernel-Subsystem, das Anwendungen ermöglicht, Dateisystemereignisse wie das Erstellen, Ändern oder Löschen von Dateien und Verzeichnissen zu überwachen.

Die Funktion gibt ein Array von assoziativen Arrays zurück, wobei jedes Element ein einzelnes Ereignis repräsentiert. Jedes Ereignis-Array enthält die Schlüssel wd (Watch-Deskriptor), mask (Ereignistyp als Bitmaske), cookie (für zusammengehörige Ereignisse wie IN_MOVED_FROM/IN_MOVED_TO) und name (betroffener Dateiname, sofern zutreffend).

Standardmäßig blockiert inotify_read(), bis mindestens ein Ereignis vorliegt. Um nicht-blockierendes Verhalten zu erreichen, kann man die Ressource mit stream_set_blocking() auf nicht-blockierend setzen oder zuvor mit inotify_queue_len() prüfen, ob Ereignisse in der Warteschlange vorhanden sind.

Die Funktion ist besonders nützlich für Datei-Watcher, Build-Systeme, automatische Reload-Mechanismen oder jede Anwendung, die auf Dateisystemänderungen reagieren muss, ohne regelmäßig pollen zu müssen.

Parameter

Name	Typ	Default	Beschreibung
$inotify_instance Pflicht	resource		Eine Inotify-Instanz, die zuvor mit `inotify_init()` erstellt wurde. Mit `inotify_add_watch()` müssen Watch-Einträge hinzugefügt worden sein, damit Ereignisse gelesen werden können.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein Array von assoziativen Arrays zurück, wobei jedes innere Array ein Inotify-Ereignis mit den Schlüsseln wd (int, Watch-Deskriptor), mask (int, Ereignis-Bitmaske), cookie (int, Verknüpfungs-Cookie) und name (string, Dateiname oder leerer String) darstellt. Gibt false zurück, wenn ein Fehler aufgetreten ist oder die Instanz im nicht-blockierenden Modus keine Ereignisse vorliegen hat.

Beispiele

Verzeichnis auf Dateiänderungen überwachen

<?php
// Inotify-Instanz erstellen
$inotify = inotify_init();

// Verzeichnis auf Erstellung und Löschung von Dateien überwachen
$watchDescriptor = inotify_add_watch(
    $inotify,
    '/tmp/mein_verzeichnis',
    IN_CREATE | IN_DELETE | IN_MODIFY
);

echo "Warte auf Ereignisse in /tmp/mein_verzeichnis ...\n";

// Ereignisse lesen (blockiert, bis ein Ereignis eintritt)
$events = inotify_read($inotify);

if ($events !== false) {
    foreach ($events as $event) {
        $mask = $event['mask'];
        $dateiname = $event['name'];

        if ($mask & IN_CREATE) {
            echo "Datei erstellt: {$dateiname}\n";
        } elseif ($mask & IN_DELETE) {
            echo "Datei gelöscht: {$dateiname}\n";
        } elseif ($mask & IN_MODIFY) {
            echo "Datei geändert: {$dateiname}\n";
        }
    }
}

// Watch entfernen und Instanz schließen
inotify_rm_watch($inotify, $watchDescriptor);
fclose($inotify);

Warte auf Ereignisse in /tmp/mein_verzeichnis ... Datei erstellt: test.txt

Nicht-blockierendes Lesen mit Ereigniswarteschlange

<?php
$inotify = inotify_init();

// Nicht-blockierenden Modus aktivieren
stream_set_blocking($inotify, false);

$wd = inotify_add_watch($inotify, '/var/www/html', IN_MODIFY | IN_CREATE);

// Ereignisschleife
for ($i = 0; $i < 10; $i++) {
    // Prüfen, ob Ereignisse in der Warteschlange vorhanden sind
    $anzahl = inotify_queue_len($inotify);

    if ($anzahl > 0) {
        $events = inotify_read($inotify);
        if ($events !== false) {
            foreach ($events as $event) {
                printf(
                    "Ereignis: mask=0x%X, datei=%s\n",
                    $event['mask'],
                    $event['name'] ?: '(kein Name)'
                );
            }
        }
    } else {
        echo "Keine Ereignisse, warte...\n";
    }

    sleep(1);
}

inotify_rm_watch($inotify, $wd);
fclose($inotify);

Keine Ereignisse, warte... Keine Ereignisse, warte... Ereignis: mask=0x100, datei=index.php

// Wichtig · Fallstricke

Systemvoraussetzung: Inotify steht nur unter Linux zur Verfügung. Die PHP-Erweiterung inotify muss installiert und aktiviert sein (pecl install inotify). Auf anderen Betriebssystemen wie macOS oder Windows ist diese Funktion nicht verfügbar.

Ressourcenlimits: Der Linux-Kernel begrenzt die Anzahl gleichzeitiger Inotify-Instanzen und Watch-Einträge pro Benutzer über die Parameter /proc/sys/fs/inotify/max_user_instances und /proc/sys/fs/inotify/max_user_watches. Bei großen Verzeichnisstrukturen sollten diese Werte ggf. erhöht werden.

Ereignisverlust: Wird die Ereigniswarteschlange zu groß (Limit: /proc/sys/fs/inotify/max_queued_events), werden überschüssige Ereignisse verworfen und stattdessen ein IN_Q_OVERFLOW-Ereignis generiert. Daher sollte inotify_read() regelmäßig aufgerufen werden.

Zusammengehörige Ereignisse: Beim Verschieben von Dateien innerhalb eines überwachten Verzeichnisses werden ein IN_MOVED_FROM- und ein IN_MOVED_TO-Ereignis erzeugt. Diese können über das cookie-Feld einander zugeordnet werden.

Siehe auch

inotify_init inotify_add_watch inotify_rm_watch inotify_queue_len stream_set_blocking stream_select