1 .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" A few pieces remain from an earlier version written in
25 .\" 2002 by Walter Harms (walter.harms@informatik.uni-oldenburg.de)
27 .TH GETGROUPLIST 3 2008-07-03 "GNU" "Linux Programmer's Manual"
29 getgrouplist \- get list of groups to which a user belongs
33 .BI "int getgrouplist(const char *" user ", gid_t " group ,
35 .BI " gid_t *" groups ", int *" ngroups );
38 Feature Test Macro Requirements for glibc (see
39 .BR feature_test_macros (7)):
47 function scans the group database (see
49 to obtain the list of groups that
54 of these groups are returned in the array
57 If it was not among the groups defined for
59 in the group database, then
61 is included in the list of groups returned by
63 typically this argument is specified as the group ID from
64 the password record for
69 argument is a value-result argument:
70 on return it always contains the number of groups found for
74 this value may be greater than the number of groups stored in
77 If the number of groups of which
79 is a member is less than or equal to
85 If the user is a member of more than
90 In this case the value returned in
92 can be used to resize the buffer passed to a further call
95 This function is present since glibc 2.2.4.
97 This function is nonstandard; it appears on most BSDs.
99 In glibc versions before 2.3.3,
100 the implementation of this function contains a buffer-overrun bug:
101 it returns the complete list of groups for
105 even when the number of groups exceeds
109 The program below displays the group list for the user named in its
110 first command-line argument.
111 The second command-line argument specifies the
113 value to be supplied to
115 The following shell session shows examples of the use of this program:
119 .RB "$" " ./a.out cecilia 0"
120 getgrouplist() returned -1; ngroups = 3
121 .RB "$" " ./a.out cecilia 3"
137 main(int argc, char *argv[])
145 fprintf(stderr, "Usage: %s <user> <ngroups>\\n", argv[0]);
149 ngroups = atoi(argv[2]);
151 groups = malloc(ngroups * sizeof (gid_t));
152 if (groups == NULL) {
157 /* Fetch passwd structure (contains first group ID for user) */
159 pw = getpwnam(argv[1]);
165 /* Retrieve group list */
167 if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) {
168 fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\\n",
173 /* Display list of retrieved groups, along with group names */
175 fprintf(stderr, "ngroups = %d\\n", ngroups);
176 for (j = 0; j < ngroups; j++) {
177 printf("%d", groups[j]);
178 gr = getgrgid(groups[j]);
180 printf(" (%s)", gr\->gr_name);