GETGROUPS(2)

NOM
getgroups, setgroups - Lire et écrire la liste des groupes supplémentaires d'un processus

SYNOPSIS
#include <sys/types.h>
#include <unistd.h>

int getgroups(int size, gid_t list[]);

#include <grp.h>

int setgroups(size_t size, const gid_t *list);

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

setgroups() : _BSD_SOURCE

DESCRIPTION

getgroups() renvoie dans la liste list les identifiants des groupes additionnels du processus appelant. Le paramètre size doit indiquer le nombre maximal d'éléments qui peuvent être stockés dans le tampon pointé par list. Si le processus appelant a plus que size groupes additionnels, cela génère une erreur. Il n'est pas spécifié si l'identifiant du groupe effectif du processus appelant est inclus dans la liste renvoyée (ainsi une application devrait également appeler getegid(2) et ajouter ou supprimer la valeur résultante). Si size vaut zéro, list n'est pas modifiée, mais le nombre total de groupes additionnels pour le processus est renvoyé. Ceci permet à l'appelant de déterminer la taille d'une liste list allouée dynamiquement à utiliser dans une appel à getgroups() ultérieur.

setgroups() définit des identifiants de groupe additionnels pour le processus appelant. Les privilèges appropriés (sous Linux : la capacité CAP_SETGID) sont nécessaires. Le paramètre size indique le nombre d'identifiants de groupe additionnels du tampon pointé par list.

VALEUR RENVOYÉE
En cas de succès, getgroups() renvoie le nombre d'identifiants de groupe additionnels. En cas d'erreur, -1 est renvoyé et errno contient le code d'erreur. En cas de succès, setgroups() renvoie 0. En cas d'erreur, -1 est renvoyé et errno contient le code d'erreur.

ERREURS

EFAULT
    list pointe en dehors de l'espace d'adressage accessible.

getgroups() peut également échouer avec les erreurs suivantes :

EINVAL
    size est inférieur au nombre d'identifiants de groupe additionnels, et n'est pas nul.

setgroups() peut également échouer avec les erreurs suivantes :

EINVAL
    size est plus grand que NGROUPS_MAX (32 avant Linux 2.6.4 ; 65536 depuis Linux 2.6.4).

ENOMEM
    Plus de mémoire disponible.

EPERM
    L'appelant n'a pas les privilèges nécessaires.

CONFORMITÉ
SVr4, BSD 4.3. getgroups() est conforme à POSIX.1-2001. Comme setgroups() nécessite des privilèges, il n'est pas couvert par POSIX.1-2001.

NOTES
Un processus peut avoir jusqu'à NGROUPS_MAX identifiants de groupe additionnels en plus de son identifiant de groupe effectif. La constante NGROUPS_MAX est définie dans <limits.h>. Le jeu d'identifiants de groupe additionnels est hérité du processus parent, et est préservé au travers des appels à execve(2). Le nombre maximal d'identifiants de groupe additionnels peut être obtenu pendant l'exécution au moyen de sysconf(3) :
    long ngroups_max;
    ngroups_max = sysconf(_SC_NGROUPS_MAX);
La valeur de retour maximale de getgroups() ne peut pas être plus grande que 1 plus cette valeur. Depuis Linux 2.6.4, le nombre maximal d’identifiants de groupe additionnels est aussi exposé à l’aide du fichier /proc/sys/kernel/ngroups_max en lecture seule et spécifique à Linux. L'appel système getgid() original de Linux ne gérait que des identifiants de groupe sur 16 bits. En conséquence, Linux 2.4 a ajouté getgroups32() qui prend en charge des identifiants 32 bits. La fonction getgroups() de la glibc qui l'encapsule gère de manière transparente ces différences entre noyaux.

VOIR AUSSI
getgid(2), setgid(2), getgrouplist(3), initgroups(3), capabilities(7), credentials(7)

COLOPHON
Cette page fait partie de la publication 3.70 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».