eio_chown — Funktion · PHP-Referenz

Signatur

eio_chown(string $path, int $uid, int $gid = -1, int $pri = EIO_PRI_DEFAULT, callable $callback = null, mixed $data = null): resource

Beschreibung

eio_chown() ist Teil der EIO-Erweiterung (Asynchronous I/O) und ermöglicht es, den Eigentümer und die Gruppe einer Datei oder eines Verzeichnisses nicht-blockierend zu ändern – ähnlich wie der POSIX-Befehl chown. Die Operation wird im Hintergrund ausgeführt, sodass der PHP-Prozess nicht auf das Ergebnis warten muss.

Der Parameter $uid gibt die neue Benutzer-ID und $gid die neue Gruppen-ID an. Wird für $gid der Wert -1 übergeben, bleibt die Gruppe unverändert. Dies entspricht dem Verhalten des POSIX-Systemaufrufs lchown/chown.

Die Priorität $pri steuert, wie dringend die Operation in der EIO-Warteschlange behandelt wird. Das Callback $callback wird aufgerufen, sobald die Operation abgeschlossen ist, und erhält als erstes Argument die in $data übergebenen Benutzerdaten, als zweites den Rückgabewert (0 bei Erfolg, -1 bei Fehler) und als drittes einen eventuellen Fehlerwert.

eio_chown() eignet sich besonders in Event-getriebenen Anwendungen (z. B. zusammen mit libeio oder dem ev-Event-Loop), in denen blockierende Dateisystemoperationen vermieden werden sollen.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Absoluter oder relativer Pfad zur Datei oder zum Verzeichnis, dessen Besitzer geändert werden soll.
$uid Pflicht	int		Neue Benutzer-ID (UID) des Eigentümers. Muss eine gültige Benutzer-ID des Systems sein.
$gid	int	-1	Neue Gruppen-ID (GID). Wird `-1` übergeben, bleibt die Gruppe der Datei unverändert.
$pri	int	EIO_PRI_DEFAULT	Priorität der Operation in der EIO-Warteschlange. Mögliche Werte: `EIO_PRI_MIN`, `EIO_PRI_DEFAULT`, `EIO_PRI_MAX`.
$callback	callable	null	Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Signatur: `function(mixed $data, int $result, resource $req): void`. `$result` ist `0` bei Erfolg, `-1` bei Fehler.
$data	mixed	null	Beliebige Benutzerdaten, die unverändert als erstes Argument an das Callback übergeben werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt bei Erfolg eine EIO-Request-Ressource zurück, mit der die Operation z. B. über eio_cancel() abgebrochen werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

Besitzer einer Datei asynchron ändern

<?php
// EIO-Erweiterung muss installiert und geladen sein

$filePath = '/tmp/testdatei.txt';
file_put_contents($filePath, 'Testinhalt');

// UID und GID des gewünschten Besitzers ermitteln
$uid = 1000; // z. B. Benutzer mit UID 1000
$gid = 1000; // z. B. Gruppe mit GID 1000

$req = eio_chown(
    $filePath,
    $uid,
    $gid,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result === 0) {
            echo "Besitzer erfolgreich geändert für: " . $data['path'] . PHP_EOL;
        } else {
            echo "Fehler beim Ändern des Besitzers: " . eio_get_last_error($req) . PHP_EOL;
        }
    },
    ['path' => $filePath]
);

// EIO-Event-Loop starten
eio_event_loop();

Besitzer erfolgreich geändert für: /tmp/testdatei.txt

Nur Benutzer ändern, Gruppe beibehalten

<?php
// GID -1 lässt die Gruppe unverändert

$filePath = '/tmp/testdatei2.txt';
file_put_contents($filePath, 'Weiterer Test');

$uid = 0; // root

$req = eio_chown(
    $filePath,
    $uid,
    -1, // Gruppe bleibt unverändert
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result === 0) {
            echo "UID erfolgreich auf root geändert." . PHP_EOL;
        } else {
            echo "Fehler: " . eio_get_last_error($req) . PHP_EOL;
        }
    }
);

eio_event_loop();

UID erfolgreich auf root geändert.

// Wichtig · Fallstricke

Berechtigungen: Das Ändern des Besitzers einer Datei setzt in der Regel root-Rechte voraus. Ohne ausreichende Berechtigungen schlägt die Operation fehl und $result im Callback ist -1. Der genaue Fehlergrund kann mit eio_get_last_error($req) abgefragt werden.

Verfügbarkeit: Die EIO-Erweiterung ist nicht standardmäßig in PHP enthalten und muss separat über PECL installiert werden (pecl install eio). Sie funktioniert nur auf POSIX-Systemen (Linux, macOS) und ist unter Windows nicht verfügbar.

Event-Loop: Die Funktion arbeitet nur korrekt im Zusammenspiel mit einem EIO-kompatiblen Event-Loop (z. B. eio_event_loop() oder dem ev-Loop). Ohne einen solchen Loop wird das Callback möglicherweise nie aufgerufen.

Siehe auch

eio_chmod chown eio_cancel eio_get_last_error eio_event_loop