1 .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" A few pieces remain from an earlier version written in
5 .\" 2002 by Walter Harms (walter.harms@informatik.uni-oldenburg.de)
7 .\" %%%LICENSE_START(VERBATIM)
8 .\" Permission is granted to make and distribute verbatim copies of this
9 .\" manual provided the copyright notice and this permission notice are
10 .\" preserved on all copies.
12 .\" Permission is granted to copy and distribute modified versions of this
13 .\" manual under the conditions for verbatim copying, provided that the
14 .\" entire resulting derived work is distributed under the terms of a
15 .\" permission notice identical to this one.
17 .\" Since the Linux kernel and libraries are constantly changing, this
18 .\" manual page may be incorrect or out-of-date. The author(s) assume no
19 .\" responsibility for errors or omissions, or for damages resulting from
20 .\" the use of the information contained herein. The author(s) may not
21 .\" have taken the same level of care in the production of this manual,
22 .\" which is licensed free of charge, as they might when working
25 .\" Formatted or processed versions of this manual, if unaccompanied by
26 .\" the source, must acknowledge the copyright and authors of this work.
29 .TH GETGROUPLIST 3 2019-03-06 "GNU" "Linux Programmer's Manual"
31 getgrouplist \- get list of groups to which a user belongs
35 .BI "int getgrouplist(const char *" user ", gid_t " group ,
37 .BI " gid_t *" groups ", int *" ngroups );
40 Feature Test Macro Requirements for glibc (see
41 .BR feature_test_macros (7)):
47 Glibc 2.19 and earlier:
52 function scans the group database (see
54 to obtain the list of groups that
59 of these groups are returned in the array
62 If it was not among the groups defined for
64 in the group database, then
66 is included in the list of groups returned by
68 typically this argument is specified as the group ID from
69 the password record for
74 argument is a value-result argument:
75 on return it always contains the number of groups found for
79 this value may be greater than the number of groups stored in
82 If the number of groups of which
84 is a member is less than or equal to
90 If the user is a member of more than
95 In this case, the value returned in
97 can be used to resize the buffer passed to a further call
100 This function is present since glibc 2.2.4.
102 For an explanation of the terms used in this section, see
108 Interface Attribute Value
111 T} Thread safety MT-Safe locale
114 This function is nonstandard; it appears on most BSDs.
116 In glibc versions before 2.3.3,
117 the implementation of this function contains a buffer-overrun bug:
118 it returns the complete list of groups for
122 even when the number of groups exceeds
126 The program below displays the group list for the user named in its
127 first command-line argument.
128 The second command-line argument specifies the
130 value to be supplied to
132 The following shell session shows examples of the use of this program:
136 .RB "$" " ./a.out cecilia 0"
137 getgrouplist() returned \-1; ngroups = 3
138 .RB "$" " ./a.out cecilia 3"
154 main(int argc, char *argv[])
162 fprintf(stderr, "Usage: %s <user> <ngroups>\en", argv[0]);
166 ngroups = atoi(argv[2]);
168 groups = malloc(ngroups * sizeof (gid_t));
169 if (groups == NULL) {
174 /* Fetch passwd structure (contains first group ID for user) */
176 pw = getpwnam(argv[1]);
182 /* Retrieve group list */
184 if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) {
185 fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\en",
190 /* Display list of retrieved groups, along with group names */
192 fprintf(stderr, "ngroups = %d\en", ngroups);
193 for (j = 0; j < ngroups; j++) {
194 printf("%d", groups[j]);
195 gr = getgrgid(groups[j]);
197 printf(" (%s)", gr\->gr_name);
208 .BR group_member (3),