eio_fchown — Funktion · PHP-Referenz

Signatur

eio_fchown(mixed $fd, int $uid, int $gid = -1, int $pri = EIO_PRI_DEFAULT, callable $callback = null, mixed $data = null): resource

Beschreibung

eio_fchown() ist Teil der eio-Erweiterung, die nicht-blockierende Datei-I/O-Operationen auf Basis der libeio-Bibliothek bereitstellt. Die Funktion entspricht dem POSIX-Systemaufruf fchown(2) und ermöglicht es, den Eigentümer und/oder die Gruppe einer offenen Datei zu ändern, ohne den PHP-Prozess zu blockieren.

Als $fd wird ein Dateideskriptor erwartet, wie er etwa von eio_open() zurückgegeben wird. Die Benutzer-ID ($uid) und Gruppen-ID ($gid) sind numerische System-IDs; ein Wert von -1 bedeutet, dass die jeweilige ID unverändert bleibt.

Die Operation wird asynchron ausgeführt. Das Ergebnis steht erst in der angegebenen $callback-Funktion zur Verfügung. Diese wird mit den Parametern $data, $result (0 bei Erfolg, -1 bei Fehler) und $req (Request-Handle) aufgerufen. Um die Event-Loop zu starten und die Callbacks abzuarbeiten, muss eio_event_loop() verwendet werden.

Diese Funktion ist besonders in Daemon-Prozessen und Hochlast-Servern nützlich, wo blockierende Systemaufrufe die Gesamtperformance beeinträchtigen würden.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Dateideskriptor der geöffneten Datei, z. B. zurückgegeben von `eio_open()`.
$uid Pflicht	int		Numerische Benutzer-ID des neuen Eigentümers. `-1` lässt die aktuelle User-ID unverändert.
$gid	int	-1	Numerische Gruppen-ID der neuen Gruppe. `-1` lässt die aktuelle Gruppen-ID unverändert.
$pri	int	EIO_PRI_DEFAULT	Priorität der Anfrage. 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($data, $result, $req): void`. `$result` ist 0 bei Erfolg, -1 bei Fehler.
$data	mixed	null	Beliebige Benutzerdaten, die unverändert an den `$callback` weitergereicht werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt bei Erfolg ein eio-Request-Handle zurück, das z. B. mit eio_cancel() abgebrochen werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

Besitzer einer Datei asynchron ändern

<?php
// eio-Erweiterung vorausgesetzt

$tmpFile = tempnam(sys_get_temp_dir(), 'eio_test_');

// Datei asynchron öffnen
eio_open(
    $tmpFile,
    EIO_O_RDWR,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) use ($tmpFile) {
        if ($result < 0) {
            echo 'Fehler beim Öffnen: ' . eio_get_last_error($req) . PHP_EOL;
            return;
        }

        $fd = $result;

        // Besitzer auf UID 1000 und GID 1000 setzen (Root-Rechte erforderlich)
        eio_fchown(
            $fd,
            1000,
            1000,
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd, $tmpFile) {
                if ($result === 0) {
                    echo 'Besitzer erfolgreich geändert.' . PHP_EOL;
                } else {
                    echo 'Fehler: ' . eio_get_last_error($req) . PHP_EOL;
                }

                // Dateideskriptor schließen
                eio_close($fd);

                // Temporäre Datei entfernen
                unlink($tmpFile);
            }
        );
    }
);

eio_event_loop();

Besitzer erfolgreich geändert.

Nur die Gruppen-ID ändern (UID unverändert lassen)

<?php
$tmpFile = tempnam(sys_get_temp_dir(), 'eio_grp_');

eio_open(
    $tmpFile,
    EIO_O_RDWR,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) use ($tmpFile) {
        if ($result < 0) {
            echo 'Öffnen fehlgeschlagen.' . PHP_EOL;
            return;
        }

        $fd = $result;

        // UID auf -1 setzen = unverändert lassen; nur GID ändern
        eio_fchown(
            $fd,
            -1,
            1000,
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd, $tmpFile) {
                echo ($result === 0)
                    ? 'Gruppe erfolgreich geändert.' . PHP_EOL
                    : 'Fehler: ' . eio_get_last_error($req) . PHP_EOL;

                eio_close($fd);
                unlink($tmpFile);
            }
        );
    }
);

eio_event_loop();

Gruppe erfolgreich geändert.

// Wichtig · Fallstricke

Berechtigungen: Das Ändern des Dateibesitzers (chown) erfordert unter Unix/Linux in der Regel Root-Rechte (UID 0). Normale Prozesse können nur die Gruppen-ID auf eine Gruppe ändern, der sie selbst angehören. Fehler durch unzureichende Rechte werden im Callback mit $result === -1 signalisiert; der genaue Fehlercode kann über eio_get_last_error($req) abgefragt werden.

Abhängigkeit: Die eio-Erweiterung ist standardmäßig nicht in PHP enthalten und muss über PECL installiert werden. Sie ist außerdem nur auf POSIX-kompatiblen Systemen (Linux, macOS) verfügbar – nicht unter Windows.

Event-Loop: Ohne den Aufruf von eio_event_loop() oder die Integration in eine externe Event-Loop (z. B. libevent oder libuv) werden die Callbacks niemals ausgeführt.

Siehe auch

eio_open eio_fchmod eio_chown eio_close eio_event_loop eio_get_last_error