GETGROUPS(2)

BEZEICHNUNG
getgroups, setgroups - abfragen/setzen von zusätzlichen Gruppen-IDs

ÜBERSICHT
#include <sys/types.h>
#include <unistd.h>

int getgroups(int groesse, gid_t liste[]);

#include <grp.h>

int setgroups(size_t groesse, const gid_t *liste);

Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

setgroups(): _BSD_SOURCE

BESCHREIBUNG

getgroups() gibt die zusätzlichen Gruppen-IDs des aufrufenden Prozesses in liste zurück. Das Argument groesse sollte auf die maximale Anzahl der Elemente gesetzt werden, die in dem Puffer gespeichert werden können, auf den liste zeigt. Falls der aufrufende Prozess Mitglied von mehr als groesse Gruppen ist, dann führt dies zu einem Fehler. Es ist nicht beschrieben, ob die effektive Gruppen-ID des aufrufenden Prozesses in der zurückgegebenen Liste enthalten ist. (Daher sollte eine Anwendung auch getegid(2) aufrufen und den resultierenden Wert hinzufügen oder entfernen.)

Wenn groesse Null ist, wird liste nicht verändert, es wird aber die Gesamtzahl der zusätzlichen Gruppen-IDs für den Prozess zurückgegeben. Dies erlaubt es dem Aufrufenden, die Größe einer dynamisch reservierten liste festzulegen, die in einem weiteren Aufruf von getgroups() benutzt wird.

setgroups() setzt die zusätzlichen Gruppen-IDs für den aufrufenden Prozess. Es werden geeignete Privilegien benötigt (Linux; die Fähigkeit CAP_SETGID). Das Argument groesse gibt die Anzahl der zusätzlichen Gruppen-IDs im Puffer an, auf den liste zeigt.

RÜCKGABEWERT
Bei Erfolg gibt getgroups() die Anzahl der zusätzlichen Gruppen-IDs zurück. Bei aufgetretenem Fehler wird -1 geliefert und errno wird entsprechend gesetzt.

Bei Erfolg gibt setgroups() 0 zurück. Bei aufgetretenem Fehler wird -1 geliefert und errno wird entsprechend gesetzt.

FEHLER

EFAULT
    liste hat eine ungültige Adresse.

getgroups() kann außerdem mit dem folgenden Fehler fehlschlagen:

EINVAL
    groesse ist kleiner als die Anzahl der zusätzlichen Gruppen-IDs, aber nicht Null.

setgroups() kann überdies mit den folgenden Fehlern fehlschlagen:

EINVAL
    groesse ist größer als NGROUPS_MAX (32 vor Linux 2.6.4; 65536 seit Linux 2.6.4).

ENOMEM
    Speicher aufgebraucht.

EPERM
    Der aufrufende Prozess hat unzureichende Rechte (es fehlt die CAP_SETGID-Capability).

EPERM (seit Linux 3.19)
    Die Verwendung von setgroups() wird in diesem User-Namensraum verweigert. Siehe die Beschreibung von /proc/[pid]/setgroups in user_namespaces(7).

KONFORM ZU
SVr4, 4.3BSD. Die Funktion getgroups() ist in POSIX.1-2001 und POSIX.1-2008 enthalten. Seit setgroups() Privilegien benötigt, ist es nicht durch POSIX.1 abgedeckt.

ANMERKUNGEN
Ein Prozess kann bis zu NGROUPS_MAX zusätzliche Gruppen-IDs ergänzend zur effektiven Gruppen-ID haben. Die Konstante NGROUPS_MAX ist in <limits.h> definiert. Die Zusammenstellung zusätzlicher Gruppen-IDs wird vom Elternprozess geerbt und über ein execve(2) aufbewahrt.

Die maximale Anzahl von zusätzlichen Gruppen-IDs kann zur Laufzeit durch Benutzung von sysconf(3) bestimmt werden:

    long ngroups_max;
    ngroups_max = sysconf(_SC_NGROUPS_MAX);

Der maximale Rückgabewert von getgroups() kann nicht um mehr als eins größer als dieser Wert sein. Seit Linux 2.6.4 wird die maximale Anzahl zusätzlicher Gruppen-IDs außerdem über die nur lesbare Linux-spezifische Datei /proc/sys/kernel/ngroups_max offengelegt.

Der Original-Linux-Systemaufruf getgroups() unterstützte nur 16-Bit-Gruppen-IDs. Nachfolgend fügte Linux 2.4 getgroups32() hinzu, das 32-Bit-IDs unterstützte. Die Glibc-Wrapper-Funktion getgroups() stellt die Änderungen transparent über Kernel-Versionen hinweg bereit.

  Unterschiede C-Bibliothek/Kernel
Auf Kernelebene sind die Benutzer-ID und die Gruppen-ID ein threadweises Attribut. POSIX gibt vor, dass alle Threads in einem Prozess gemeinsame Legitimierungsdaten (Credentials) haben. Die NPTL-Threading-Implementierung setzt die POSIX-Vorgaben durch Wrapper-Funktionen für die verschiedenen Systemaufrufe um, welche die Benutzer- und Gruppen-IDs entsprechend ändern. Diese Wrapper-Funktionen (zum Beispiel jene für setgroups()) nutzen eine signalbasierte Technik, um die Legitimierungsdaten aller Threads in einem Prozess zu ändern, wenn ein Prozess diese Daten ändert. Details hierzu finden Sie in nptl(7).

SIEHE AUCH
getgid(2), setgid(2), getgrouplist(3), group_member(3), initgroups(3), capabilities(7), credentials(7)

KOLOPHON
Diese Seite ist Teil der Veröffentlichung 4.04 des Projekts Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie Fehler gemeldet werden können sowie die aktuelle Version dieser Seite finden sich unter http://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von René Tschirley <gremlin@cs.tu-berlin.de>, Martin Schulze <joey@infodrom.org>, Chris Leick <c.leick@vollbio.de> und Mario Blättermann <mario.blaettermann@gmail.com> erstellt.

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.

Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an <debian-l10n-german@lists.debian.org>.