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 2014-08-19 "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)):
49 function scans the group database (see
51 to obtain the list of groups that
56 of these groups are returned in the array
59 If it was not among the groups defined for
61 in the group database, then
63 is included in the list of groups returned by
65 typically this argument is specified as the group ID from
66 the password record for
71 argument is a value-result argument:
72 on return it always contains the number of groups found for
76 this value may be greater than the number of groups stored in
79 If the number of groups of which
81 is a member is less than or equal to
87 If the user is a member of more than
92 In this case, the value returned in
94 can be used to resize the buffer passed to a further call
97 This function is present since glibc 2.2.4.
99 This function is nonstandard; it appears on most BSDs.
101 In glibc versions before 2.3.3,
102 the implementation of this function contains a buffer-overrun bug:
103 it returns the complete list of groups for
107 even when the number of groups exceeds
111 The program below displays the group list for the user named in its
112 first command-line argument.
113 The second command-line argument specifies the
115 value to be supplied to
117 The following shell session shows examples of the use of this program:
121 .RB "$" " ./a.out cecilia 0"
122 getgrouplist() returned \-1; ngroups = 3
123 .RB "$" " ./a.out cecilia 3"
139 main(int argc, char *argv[])
147 fprintf(stderr, "Usage: %s <user> <ngroups>\\n", argv[0]);
151 ngroups = atoi(argv[2]);
153 groups = malloc(ngroups * sizeof (gid_t));
154 if (groups == NULL) {
159 /* Fetch passwd structure (contains first group ID for user) */
161 pw = getpwnam(argv[1]);
167 /* Retrieve group list */
169 if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) {
170 fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\\n",
175 /* Display list of retrieved groups, along with group names */
177 fprintf(stderr, "ngroups = %d\\n", ngroups);
178 for (j = 0; j < ngroups; j++) {
179 printf("%d", groups[j]);
180 gr = getgrgid(groups[j]);
182 printf(" (%s)", gr\->gr_name);
193 .BR group_member (3),