Debian Codegraph @

upstream/debian-unstable/man3/getgrouplist.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH getgrouplist 3 2025-09-21 "Linux man-pages 6.18"
7 .SH NAME
8 getgrouplist \- get list of groups to which a user belongs
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <grp.h>
15 .P
16 .BI "int getgrouplist(const char *" user ", gid_t " group ,
17 .BI " gid_t *" groups ", int *" ngroups );
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR getgrouplist ():
26 .nf
27 Since glibc 2.19:
28 _DEFAULT_SOURCE
29 glibc 2.19 and earlier:
30 _BSD_SOURCE
31 .fi
32 .SH DESCRIPTION
33 The
34 .BR getgrouplist ()
35 function scans the group database (see
36 .BR group (5))
37 to obtain the list of groups that
38 .I user
39 belongs to.
40 Up to
41 .I *ngroups
42 of these groups are returned in the array
43 .IR groups .
44 .P
45 If it was not among the groups defined for
46 .I user
47 in the group database, then
48 .I group
49 is included in the list of groups returned by
50 .BR getgrouplist ();
51 typically this argument is specified as the group ID from
52 the password record for
53 .IR user .
54 .P
55 The
56 .I ngroups
57 argument is a value-result argument:
58 on return it always contains the number of groups found for
59 .IR user ,
60 including
61 .IR group ;
62 this value may be greater than the number of groups stored in
63 .IR groups .
64 .SH RETURN VALUE
65 If the number of groups of which
66 .I user
67 is a member is less than or equal to
68 .IR *ngroups ,
69 then the value
70 .I *ngroups
71 is returned.
72 .P
73 If the user is a member of more than
74 .I *ngroups
75 groups, then
76 .BR getgrouplist ()
77 returns \-1.
78 In this case, the value returned in
79 .I *ngroups
80 can be used to resize the buffer passed to a further call to
81 .BR getgrouplist ().
82 .SH ATTRIBUTES
83 For an explanation of the terms used in this section, see
84 .BR attributes (7).
85 .TS
86 allbox;
87 lbx lb lb
88 l l l.
89 Interface Attribute Value
90 T{
91 .na
92 .nh
93 .BR getgrouplist ()
94 T} Thread safety MT-Safe locale
95 .TE
96 .SH STANDARDS
97 None.
98 .SH HISTORY
99 glibc 2.2.4.
100 .SH BUGS
101 Before glibc 2.3.3,
102 the implementation of this function contains a buffer-overrun bug:
103 it returns the complete list of groups for
104 .I user
105 in the array
106 .IR groups ,
107 even when the number of groups exceeds
108 .IR *ngroups .
109 .SH EXAMPLES
110 The program below displays the group list for the user named in its
111 first command-line argument.
112 The second command-line argument specifies the
113 .I ngroups
114 value to be supplied to
115 .BR getgrouplist ().
116 The following shell session shows examples of the use of this program:
117 .P
118 .in +4n
119 .EX
120 .RB "$" " ./a.out cecilia 0"
121 getgrouplist() returned \-1
122 ngroups = 3
123 .RB "$" " ./a.out cecilia 3"
124 ngroups = 3
125 16 (dialout)
126 33 (video)
127 100 (users)
128 .EE
129 .in
130 .SS Program source
131 \&
132 .\" SRC BEGIN (getgrouplist.c)
133 .EX
134 #include <errno.h>
135 #include <grp.h>
136 #include <pwd.h>
137 #include <stdio.h>
138 #include <stdlib.h>
139 \&
140 int
141 main(int argc, char *argv[])
142 {
143 int ngroups;
144 gid_t *groups;
145 struct group *gr;
146 struct passwd *pw;
147 \&
148 if (argc != 3) {
149 fprintf(stderr, "Usage: %s <user> <ngroups>\[rs]n", argv[0]);
150 exit(EXIT_FAILURE);
151 }
152 \&
153 ngroups = atoi(argv[2]);
154 \&
155 groups = malloc(sizeof(*groups) * ngroups);
156 if (groups == NULL) {
157 perror("malloc");
158 exit(EXIT_FAILURE);
159 }
160 \&
161 /* Fetch passwd structure (contains first group ID for user). */
162 \&
163 errno = 0;
164 pw = getpwnam(argv[1]);
165 if (pw == NULL) {
166 if (errno)
167 perror("getpwnam");
168 else
169 fprintf(stderr, "no such user\[rs]n");
170 exit(EXIT_FAILURE);
171 }
172 \&
173 /* Retrieve group list. */
174 \&
175 if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) {
176 fprintf(stderr, "getgrouplist() returned \-1\[rs]n");
177 fprintf(stderr, "ngroups = %d\[rs]n", ngroups);
178 exit(EXIT_FAILURE);
179 }
180 \&
181 /* Display list of retrieved groups, along with group names. */
182 \&
183 fprintf(stderr, "ngroups = %d\[rs]n", ngroups);
184 for (int j = 0; j < ngroups; j++) {
185 printf("%d", groups[j]);
186 gr = getgrgid(groups[j]);
187 if (gr != NULL)
188 printf(" (%s)", gr\->gr_name);
189 printf("\[rs]n");
190 }
191 \&
192 exit(EXIT_SUCCESS);
193 }
194 .EE
195 .\" SRC END
196 .SH SEE ALSO
197 .BR getgroups (2),
198 .BR setgroups (2),
199 .BR getgrent (3),
200 .BR group_member (3),
201 .BR group (5),
202 .BR passwd (5)