getgrouplist(3)

1GETGROUPLIST(3)            Linux Programmer's Manual           GETGROUPLIST(3)
2
3
4

NAME

6       getgrouplist - get list of groups to which a user belongs
7

SYNOPSIS

9       #include <grp.h>
10
11       int getgrouplist(const char *user, gid_t group,
12                        gid_t *groups, int *ngroups);
13
14   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
15
16       getgrouplist():
17           Since glibc 2.19:
18               _DEFAULT_SOURCE
19           Glibc 2.19 and earlier:
20               _BSD_SOURCE
21

DESCRIPTION

23       The  getgrouplist() function scans the group database (see group(5)) to
24       obtain the list of groups that user belongs  to.   Up  to  *ngroups  of
25       these groups are returned in the array groups.
26
27       If  it was not among the groups defined for user in the group database,
28       then group is included in the  list  of  groups  returned  by  getgrou‐
29       plist();  typically this argument is specified as the group ID from the
30       password record for user.
31
32       The ngroups argument is a value-result argument: on  return  it  always
33       contains  the  number  of  groups found for user, including group; this
34       value may be greater than the number of groups stored in groups.
35

RETURN VALUE

37       If the number of groups of which user is a member is less than or equal
38       to *ngroups, then the value *ngroups is returned.
39
40       If  the  user  is  a member of more than *ngroups groups, then getgrou‐
41       plist() returns -1.  In this case, the value returned in  *ngroups  can
42       be used to resize the buffer passed to a further call getgrouplist().
43

VERSIONS

45       This function is present since glibc 2.2.4.
46

ATTRIBUTES

48       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
49       tributes(7).
50
51       ┌─────────────────────────────────────┬───────────────┬────────────────┐
52       │Interface                            │ Attribute     │ Value          │
53       ├─────────────────────────────────────┼───────────────┼────────────────┤
54       │getgrouplist()                       │ Thread safety │ MT-Safe locale │
55       └─────────────────────────────────────┴───────────────┴────────────────┘
56

CONFORMING TO

58       This function is nonstandard; it appears on most BSDs.
59

BUGS

61       In glibc versions before 2.3.3, the  implementation  of  this  function
62       contains  a  buffer-overrun bug: it returns the complete list of groups
63       for user in the array groups, even when the number  of  groups  exceeds
64       *ngroups.
65

EXAMPLES

67       The  program  below  displays  the group list for the user named in its
68       first command-line argument.  The second command-line  argument  speci‐
69       fies the ngroups value to be supplied to getgrouplist().  The following
70       shell session shows examples of the use of this program:
71
72           $ ./a.out cecilia 0
73           getgrouplist() returned -1; ngroups = 3
74           $ ./a.out cecilia 3
75           ngroups = 3
76           16 (dialout)
77           33 (video)
78           100 (users)
79
80   Program source
81
82       #include <stdio.h>
83       #include <stdlib.h>
84       #include <grp.h>
85       #include <pwd.h>
86
87       int
88       main(int argc, char *argv[])
89       {
90           int ngroups;
91           struct passwd *pw;
92           struct group *gr;
93
94           if (argc != 3) {
95               fprintf(stderr, "Usage: %s <user> <ngroups>\n", argv[0]);
96               exit(EXIT_FAILURE);
97           }
98
99           ngroups = atoi(argv[2]);
100
101           gid_t *groups = malloc(sizeof(*groups) * ngroups);
102           if (groups == NULL) {
103               perror("malloc");
104               exit(EXIT_FAILURE);
105           }
106
107           /* Fetch passwd structure (contains first group ID for user). */
108
109           pw = getpwnam(argv[1]);
110           if (pw == NULL) {
111               perror("getpwnam");
112               exit(EXIT_SUCCESS);
113           }
114
115           /* Retrieve group list. */
116
117           if (getgrouplist(argv[1], pw->pw_gid, groups, &ngroups) == -1) {
118               fprintf(stderr, "getgrouplist() returned -1; ngroups = %d\n",
119                       ngroups);
120               exit(EXIT_FAILURE);
121           }
122
123           /* Display list of retrieved groups, along with group names. */
124
125           fprintf(stderr, "ngroups = %d\n", ngroups);
126           for (int j = 0; j < ngroups; j++) {
127               printf("%d", groups[j]);
128               gr = getgrgid(groups[j]);
129               if (gr != NULL)
130                   printf(" (%s)", gr->gr_name);
131               printf("\n");
132           }
133
134           exit(EXIT_SUCCESS);
135       }
136

COLOPHON

142       This  page  is  part of release 5.13 of the Linux man-pages project.  A
143       description of the project, information about reporting bugs,  and  the
144       latest     version     of     this    page,    can    be    found    at
145       https://www.kernel.org/doc/man-pages/.
146
147
148
149GNU                               2021-03-22                   GETGROUPLIST(3)