Debian Codegraph @

upstream/debian-trixie/man3/getgrouplist.3

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