posix_getpwnam — Funktion · PHP-Referenz

Signatur

posix_getpwnam(string $username): array|false

Beschreibung

posix_getpwnam() liest den Eintrag des angegebenen Benutzers aus der Systempasswortdatenbank (typischerweise /etc/passwd oder einem NSS-Backend wie LDAP) und gibt dessen Daten als assoziatives Array zurück. Die Funktion ist nützlich, wenn ein PHP-Skript auf Unix-Systemen Benutzerkonten verwaltet, Dateirechte prüft oder Prozesse unter einem bestimmten Benutzer starten soll.

Das zurückgegebene Array enthält die Schlüssel name, passwd, uid, gid, gecos, dir und shell. Das Feld passwd enthält in modernen Systemen meist nur einen Platzhalter (x), da das eigentliche Passwort-Hash in der Shadow-Datei gespeichert wird.

Die Funktion steht nur auf POSIX-konformen Systemen (Linux, macOS, BSD) zur Verfügung und ist unter Windows nicht vorhanden. Sie ist Teil der POSIX-Erweiterung, die standardmäßig in den meisten PHP-Installationen auf Unix enthalten ist.

Parameter

Name	Typ	Default	Beschreibung
$username Pflicht	string		Der Anmeldename des Benutzers, dessen Informationen abgerufen werden sollen (z. B. `'www-data'` oder `'root'`).

Rückgabewert

Typ

array|false

Beschreibung

Gibt bei Erfolg ein assoziatives Array mit den Schlüsseln name (Benutzername), passwd (Passwort-Platzhalter), uid (numerische User-ID), gid (numerische Gruppen-ID), gecos (GECOS-Informationsfeld, z. B. vollständiger Name), dir (Home-Verzeichnis) und shell (Standard-Shell) zurück. Bei Fehler oder wenn der Benutzer nicht gefunden wird, wird false zurückgegeben.

Beispiele

Benutzerinformationen des aktuellen Prozessbenutzers abrufen

<?php
// Aktuellen Benutzernamen des laufenden Prozesses ermitteln
$currentUid = posix_getuid();
$pwEntry    = posix_getpwuid($currentUid);
$username   = $pwEntry['name'];

// Nun alle Informationen über diesen Benutzer laden
$info = posix_getpwnam($username);

if ($info !== false) {
    echo 'Benutzername : ' . $info['name']  . PHP_EOL;
    echo 'UID          : ' . $info['uid']   . PHP_EOL;
    echo 'GID          : ' . $info['gid']   . PHP_EOL;
    echo 'Home-Dir     : ' . $info['dir']   . PHP_EOL;
    echo 'Shell        : ' . $info['shell'] . PHP_EOL;
    echo 'GECOS        : ' . $info['gecos'] . PHP_EOL;
} else {
    echo 'Benutzer nicht gefunden.';
}

Benutzername : www-data UID : 33 GID : 33 Home-Dir : /var/www Shell : /usr/sbin/nologin GECOS : www-data

Prüfen, ob ein Benutzerkonto existiert

<?php
function userExists(string $username): bool
{
    return posix_getpwnam($username) !== false;
}

$candidates = ['root', 'www-data', 'nichtvorhanden'];

foreach ($candidates as $user) {
    $exists = userExists($user) ? 'vorhanden' : 'nicht gefunden';
    echo "Benutzer '{$user}': {$exists}" . PHP_EOL;
}

Benutzer 'root': vorhanden Benutzer 'www-data': vorhanden Benutzer 'nichtvorhanden': nicht gefunden

// Wichtig · Fallstricke

Sicherheitshinweis: Übergeben Sie niemals ungeprüfte Benutzereingaben direkt als $username. Auch wenn die Funktion selbst keine Shell-Befehle ausführt, können die zurückgegebenen Werte (z. B. dir oder shell) aus dem Array unsicher weiterverwendet werden. Validieren Sie den Benutzernamen immer gegen ein Whitelist-Muster (z. B. preg_match('/^[a-z_][a-z0-9_-]{0,31}$/i', $username)).

Die Funktion ist nicht unter Windows verfügbar. Prüfen Sie mit function_exists('posix_getpwnam') die Verfügbarkeit, wenn Ihr Code plattformübergreifend sein soll.

Das Feld passwd enthält auf modernen Systemen mit Shadow-Passwortdatei (/etc/shadow) lediglich x als Platzhalter und gibt keinen Aufschluss über das tatsächliche Passwort-Hash.

Siehe auch

posix_getpwuid posix_getuid posix_getgrgid posix_getgrnam posix_geteuid