getgrouplist(3)

1getgrouplist(3)            Library Functions Manual            getgrouplist(3)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ATTRIBUTES

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

STANDARDS

59       None.
60

HISTORY

62       glibc 2.2.4.
63

BUGS

65       Before glibc 2.3.3, the implementation of this function contains a buf‐
66       fer-overrun bug: it returns the complete list of groups for user in the
67       array groups, even when the number of groups exceeds *ngroups.
68

EXAMPLES

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