# getgrouplist

## NAME



           getgrouplist - get list of groups to which a user belongs
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <grp.h>**
    
           **int getgrouplist(const char ***_user_**, gid_t** _group_**,**
                            **gid_t ***_groups_**, int ***_ngroups_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **getgrouplist**():
               Since glibc 2.19:
                   _DEFAULT_SOURCE
               glibc 2.19 and earlier:
                   _BSD_SOURCE
    


## DESCRIPTION



           The **getgrouplist**() function scans the group database (see
           group(5)) to obtain the list of groups that _user_ belongs to.  Up
           to _*ngroups_ of these groups are returned in the array _groups_.
    
           If it was not among the groups defined for _user_ in the group
           database, then _group_ is included in the list of groups returned by
           **getgrouplist**(); typically this argument is specified as the group
           ID from the password record for _user_.
    
           The _ngroups_ argument is a value-result argument: on return it
           always contains the number of groups found for _user_ , including
           _group_ ; this value may be greater than the number of groups stored
           in _groups_.
    


## RETURN VALUE



           If the number of groups of which _user_ is a member is less than or
           equal to _*ngroups_ , then the value _*ngroups_ is returned.
    
           If the user is a member of more than _*ngroups_ groups, then
           **getgrouplist**() returns -1.  In this case, the value returned in
           _*ngroups_ can be used to resize the buffer passed to a further call
           to **getgrouplist**().
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌───────────────────────────────┬───────────────┬────────────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├───────────────────────────────┼───────────────┼────────────────┤
           │ **getgrouplist**()                │ Thread safety │ MT-Safe locale │
           └───────────────────────────────┴───────────────┴────────────────┘
    


## STANDARDS



           None.
    


## BUGS



           Before glibc 2.3.3, the implementation of this function contains a
           buffer-overrun bug: it returns the complete list of groups for
           _user_ in the array _groups_ , even when the number of groups exceeds
           _*ngroups_.
    


## EXAMPLES



           The program below displays the group list for the user named in
           its first command-line argument.  The second command-line argument
           specifies the _ngroups_ value to be supplied to **getgrouplist**().  The
           following shell session shows examples of the use of this program:
    
               $ **./a.out cecilia 0**
               getgrouplist() returned -1; ngroups = 3
               $ **./a.out cecilia 3**
               ngroups = 3
               16 (dialout)
               33 (video)
               100 (users)
    
       **Program source**
    
           #include <errno.h>
           #include <grp.h>
           #include <pwd.h>
           #include <stdio.h>
           #include <stdlib.h>
    
           int
           main(int argc, char *argv[])
           {
               int            ngroups;
               gid_t          *groups;
               struct group   *gr;
               struct passwd  *pw;
    
               if (argc != 3) {
                   fprintf(stderr, "Usage: %s <user> <ngroups>\n", argv[0]);
                   exit(EXIT_FAILURE);
               }
    
               ngroups = atoi(argv[2]);
    
               groups = malloc(sizeof(*groups) * ngroups);
               if (groups == NULL) {
                   perror("malloc");
                   exit(EXIT_FAILURE);
               }
    
               /* Fetch passwd structure (contains first group ID for user). */
    
               errno = 0;
               pw = getpwnam(argv[1]);
               if (pw == NULL) {
                   if (errno)
                       perror("getpwnam");
                   else
                       fprintf(stderr, "no such user\n");
                   exit(EXIT_FAILURE);
               }
    
               /* 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 (int 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);
           }
    


* * *