eio_utime — Funktion · PHP-Referenz

Signatur

eio_utime(string $path, float $atime, float $mtime, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

Beschreibung

eio_utime() ist Teil der EIO-Erweiterung (Event I/O), die nicht-blockierende Dateioperationen für PHP ermöglicht. Die Funktion setzt die Zugriffs- (atime) und Änderungszeit (mtime) einer Datei asynchron – der PHP-Prozess wird also während der Operation nicht blockiert.

Dies ist besonders nützlich in ereignisgesteuerten Anwendungen (z. B. mit libevent oder ReactPHP), wo blockierende Systemaufrufe vermieden werden sollen. Intern entspricht die Funktion dem POSIX-Systemaufruf utime(2) bzw. utimes(2).

Die Zeitangaben werden als float-Werte übergeben, was Sekunden mit Dezimalstellen (Mikrosekunden-Präzision) ermöglicht. Sobald die Operation abgeschlossen ist, wird die angegebene $callback-Funktion aufgerufen.

Zum Ausführen von EIO-Anfragen muss die Event-Schleife aktiv sein (z. B. über eio_event_loop()).

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Pfad zur Datei, deren Zeitstempel geändert werden sollen.
$atime Pflicht	float		Neuer Zugriffszeitstempel (access time) als Unix-Timestamp (ggf. mit Dezimalstellen für Mikrosekunden).
$mtime Pflicht	float		Neuer Änderungszeitstempel (modification time) als Unix-Timestamp (ggf. mit Dezimalstellen für Mikrosekunden).
$pri	int	EIO_PRI_DEFAULT	Priorität der Anfrage. Mögliche Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`.
$callback	callable	NULL	Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Signatur: `function($data, $result, $req): void`. `$result` ist `0` bei Erfolg oder `-1` bei Fehler.
$data	mixed	NULL	Beliebige benutzerdefinierte Daten, die unverändert an den Callback weitergegeben werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt bei Erfolg eine EIO-Anfrage-Ressource zurück, oder false im Fehlerfall. Diese Ressource kann z. B. mit eio_cancel() verwendet werden, um die Anfrage abzubrechen.

Beispiele

Zeitstempel einer Datei asynchron ändern

<?php
// Voraussetzung: EIO-Erweiterung muss installiert und aktiviert sein

$datei = '/tmp/testdatei.txt';
file_put_contents($datei, 'EIO-Test');

$neueAtime = microtime(true) - 3600; // 1 Stunde in der Vergangenheit
$neueMtime = microtime(true) - 7200; // 2 Stunden in der Vergangenheit

eio_utime(
    $datei,
    $neueAtime,
    $neueMtime,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result === 0) {
            echo "Zeitstempel erfolgreich geändert für: " . $data . PHP_EOL;
            $stat = stat($data);
            echo "Neue atime: " . date('Y-m-d H:i:s', $stat['atime']) . PHP_EOL;
            echo "Neue mtime: " . date('Y-m-d H:i:s', $stat['mtime']) . PHP_EOL;
        } else {
            echo "Fehler beim Ändern der Zeitstempel." . PHP_EOL;
        }
    },
    $datei
);

eio_event_loop();

Zeitstempel erfolgreich geändert für: /tmp/testdatei.txt Neue atime: 2024-01-01 12:00:00 Neue mtime: 2024-01-01 11:00:00

Fehlerbehandlung und Anfrage abbrechen

<?php
// Anfrage mit Möglichkeit zum Abbrechen
$req = eio_utime(
    '/tmp/nicht_vorhanden.txt',
    time(),
    time(),
    EIO_PRI_MIN,
    function ($data, $result, $req) {
        if ($result === -1) {
            echo "Fehler: Datei konnte nicht aktualisiert werden." . PHP_EOL;
            echo "EIO-Fehler: " . eio_get_last_error($req) . PHP_EOL;
        } else {
            echo "Zeitstempel gesetzt." . PHP_EOL;
        }
    }
);

if ($req === false) {
    echo "EIO-Anfrage konnte nicht erstellt werden." . PHP_EOL;
} else {
    eio_event_loop();
}

Fehler: Datei konnte nicht aktualisiert werden. EIO-Fehler: No such file or directory

// Wichtig · Fallstricke

Abhängigkeit: eio_utime() ist nur verfügbar, wenn die eio-PECL-Erweiterung installiert ist. Sie ist nicht Teil der Standard-PHP-Distribution und muss separat installiert werden (pecl install eio).

Event-Schleife erforderlich: Die asynchrone Operation wird erst ausgeführt, wenn die EIO-Event-Schleife läuft. Ohne Aufruf von eio_event_loop() (oder eine Integration in eine externe Event-Schleife) wird der Callback nie ausgeführt.

Berechtigungen: Das PHP-Skript benötigt die notwendigen Dateisystem-Berechtigungen, um die Zeitstempel der Zieldatei zu ändern. Andernfalls schlägt die Operation fehl und $result im Callback ist -1.

Als synchrone Alternative kann touch() verwendet werden, das ebenfalls Zugriffs- und Änderungszeitstempel setzen kann, jedoch den Prozess blockiert.

Siehe auch

eio_open eio_chmod eio_chown eio_stat eio_event_loop eio_cancel touch