getgroups(2)

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

BIBLIOTHEK
Standard-C-Bibliothek (libc, -lc)

ÜBERSICHT
#include <unistd.h>

int getgroups(int Größe, gid_t Liste[_Nullable Größe]);

#include <grp.h>

int setgroups(size_t Größe, const gid_t Liste[Größe]);

    Mit Glibc erforderliche Feature-Test-Makros (siehe feature_test_macros(7)):

setgroups():
    Seit Glibc 2.19:
        _DEFAULT_SOURCE
    Glibc 2.19 und älter:
        _BSD_SOURCE

BESCHREIBUNG
getgroups() gibt die zusätzlichen Gruppenkennungen des aufrufenden Prozesses in Liste zurück. Das Argument Größe 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 Größe zusätzlichen Gruppen ist, führt dies zu einem Fehler.

Es ist nicht beschrieben, ob die effektive Gruppenkennungen 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 Größe Null ist, wird liste nicht verändert, es wird aber die Gesamtzahl der zusätzlichen Gruppenkennungen 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 Gruppenkennungen für den aufrufenden Prozess. Es werden geeignete Privilegien benötigt (siehe die Beschreibung des Fehlers EPERM unten). Das Argument Größe gibt die Anzahl der zusätzlichen Gruppenkennungen im Puffer an, auf den Liste zeigt. Ein Prozess kann sämtliche zusätzliche Gruppen mit folgendem Aufruf abgeben:

    setgroups(0, (gid_t [0]){});

RÜCKGABEWERT
Bei Erfolg gibt getgroups() die Anzahl der zusätzlichen Gruppenkennungen zurück. Bei aufgetretenem Fehler wird -1 geliefert und errno wird gesetzt, um den Fehler anzuzeigen.

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

FEHLER

EFAULT
    liste hat eine ungültige Adresse.

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

EINVAL
    Größe ist kleiner als die Anzahl der zusätzlichen Gruppenkennungen, aber nicht Null.

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

EINVAL
    Größe 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 (dem Aufrufenden fehlt die CAP_SETGID-Capability in dem Benutzernamensraum, in dem er sich befindet).

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

VERSIONEN

  Unterschiede C-Bibliothek/Kernel
Auf der Kernelebene sind Benutzer- und Gruppenkennungen Attribute pro Thread. POSIX verlangt aber, dass sich alle Threads in einem Prozess die gleichen Berechtigungsnachweise teilen. Die NPTL-Threading-Implementierung behandelt die POSIX-Anforderungen durch Bereitstellung von Wrapper-Funktionen für die verschiedenen Systemaufrufe, die die UIDs und GIDs der Prozesse ändern. Diese Wrapper-Funktionen (darunter die für setgroups()) verwenden eine signalbasierte Technik, um sicherzustellen, dass bei der Änderung der Berechtigungsnachweise eines Threads auch alle anderen Threads des Prozesses ihre Berechtigungsnachweise ändern. Für Details siehe nptl(7).

STANDARDS

getgroups()
    POSIX.1-2024.

setgroups()
    Keine.

GESCHICHTE

getgroups()
    4.3BSD, SVr4, POSIX.1-1988.

setgroups()
    SVr4, 4.3BSD. Da setgroups() Privilegien benötigt, ist es nicht durch POSIX.1 abgedeckt.

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

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

Die maximale Anzahl von zusätzlichen Gruppenkennungen 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 Gruppenkennungen außerdem über die nur lesbare Linux-spezifische Datei /proc/sys/kernel/ngroups_max offengelegt.

BEISPIELE
    #include <err.h>
    #include <stddef.h>
    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <sys/types.h>
    #include <unistd.h>

    #define MALLOC(n, T)  ((T *) reallocarray(NULL, n, sizeof(T)))

    static gid_t *agetgroups(size_t *ngids);

    int
    main(void)
    {
        gid_t   *gids;
        size_t  n;

        gids = agetgroups(&n);
        if (gids == NULL)
            err(EXIT_FAILURE, "agetgroups");

        if (n != 0) {
            printf("%jd", (intmax_t) gids[0]);
            for (size_t i = 1; i < n; i++)
                printf(" %jd", (intmax_t) gids[i]);
        }
        puts("");

        free(gids);
        exit(EXIT_SUCCESS);
    }

    static gid_t *
    agetgroups(size_t *ngids)
    {
        int    n;
        gid_t  *gids;

        n = getgroups(0, NULL);
        if (n == -1)
            return NULL;

        gids = MALLOC(n, gid_t);
        if (gids == NULL)
            return NULL;

        n = getgroups(n, gids);
        if (n == -1) {
            free(gids);
            return NULL;
        }

        *ngids = n;
        return gids;
    }

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

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

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 (https://www.gnu.org/licenses/gpl-3.0.html) 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 die Mailingliste der Übersetzer: debian-l10n-german@lists.debian.org.