GETGROUPLIST(3)

NOM
getgrouplist - Obtenir la liste des groupes auquels appartient un utilisateur

SYNOPSIS
#include <grp.h>

int getgrouplist(const char *user, gid_t group,
gid_t *groups, int *ngroups);

Exigences de macros de test de fonctionnalités pour la glibc (voir feature_test_macros(7)) :

getgrouplist() : _BSD_SOURCE

DESCRIPTION
La fonction getgrouplist() balaie la base de données des groupes (voir group(5)) pour obtenir la liste des groupes auxquels appartient l'utilisateur user. Jusqu'à *ngroups de ces groupes sont retournés dans le tableau groups. S'il n'était pas parmi les groupes définis pour l'utilisateur user dans la base de données des groupes, group est inclus dans la liste des groupes retournée par getgrouplist() ; typiquement, cet argument est spécifié comme étant le GID de l'utilisateur user pris dans l'enregistrement correspondant dans le fichier des mots de passe. L'argument ngroups est un argument « valeur résultat » : au retour, il contient toujours le nombre de groupes trouvés pour l'utilisateur user, incluant group ; cette valeur peut être supérieure au nombre de groupes enregistrés dans groups.

VALEUR RENVOYÉE
Si le nombre de groupes auquel l'utilisateur user appartient est inférieur ou égal à *ngroups, la valeur *ngroups est renvoyée. Si l'utilisateur appartient à plus de *ngroups groupes, getgrouplist() renvoie -1. Dans ce cas, la valeur renvoyée dans *ngroups peut être utilisée pour redimensionner le tampon passé à un appel getgrouplist() ultérieur.

VERSIONS
Cette fonction est présente depuis glibc 2.2.4.

CONFORMITÉ
Cette fonction n'est pas standard ; elle apparaît sur la plupart des BSD.

BOGUES
Dans les versions de la glibc antérieures à la 2.3.3, l'implémentation de cette fonction comportait un bogue de débordement de tampon : elle renvoyait la liste complète des groupes de l'utilisateur user dans le tableau groups, même si le nombre de groupes était supérieur à *ngroups.

EXEMPLE

Le programme ci-dessous affiche la liste des groupes auxquels appartient l'utilisateur indiqué comme premier argument de la ligne de commande. Le second argument indique la valeur ngroups à passer à getgrouplist(). La session shell suivante montre des exemples d'utilisation de ce programme :
$ ./a.out cecilia 0
getgrouplist() returned -1; ngroups = 3
$ ./a.out cecilia 3
ngroups = 3
16 (dialout)
33 (video)
100 (users)

#include <stdio.h>
#include <stdlib.h>
#include <grp.h>
#include <pwd.h>
int
main(int argc, char *argv[])
{
    int j, ngroups;
    gid_t *groups;
    struct passwd *pw;
    struct group *gr;
    if (argc != 3) {
        fprintf(stderr, "Usage: %s <user> <ngroups>\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    ngroups = atoi(argv[2]);
    groups = malloc(ngroups * sizeof (gid_t));
    if (groups == NULL) {
        perror("malloc");
        exit(EXIT_FAILURE);
    }
    /* Fetch passwd structure (contains first group ID for user) */
    pw = getpwnam(argv[1]);
    if (pw == NULL) {
        perror("getpwnam");
        exit(EXIT_SUCCESS);
    }
    /* Retrieve group list */
    if (getgrouplist(argv[1], pw->pw_gid, groups, &ngroups) == -1) {
        fprintf(stderr, "getgrouplist() returned -1; ngroups = %d\n",
                ngroups);
	exit(EXIT_FAILURE);
    }
    /* Display list of retrieved groups, along with group names */
    fprintf(stderr, "ngroups = %d\n", ngroups);
    for (j = 0; j < ngroups; j++) {
        printf("%d", groups[j]);
        gr = getgrgid(groups[j]);
        if (gr != NULL)
            printf(" (%s)", gr->gr_name);
        printf("\n");
    }
    exit(EXIT_SUCCESS);
}

VOIR AUSSI
getgroups(2), setgroups(2), getgrent(3), group(5), passwd(5)

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 20 juillet 2005 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 getgrouplist ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.