]>
Commit | Line | Data |
---|---|---|
307b4a04 MK |
1 | .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
fea681da | 3 | .\" |
87fb0df8 MK |
4 | .\" A few pieces remain from an earlier version written in |
5 | .\" 2002 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) | |
6 | .\" | |
5fbde956 | 7 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
307b4a04 | 8 | .\" |
1d767b55 | 9 | .TH GETGROUPLIST 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
fea681da | 10 | .SH NAME |
307b4a04 | 11 | getgrouplist \- get list of groups to which a user belongs |
42009080 AC |
12 | .SH LIBRARY |
13 | Standard C library | |
14 | .RI ( libc ", " \-lc ) | |
fea681da | 15 | .SH SYNOPSIS |
c7db92b9 | 16 | .nf |
fea681da | 17 | .B #include <grp.h> |
68e4db0a | 18 | .PP |
b9f02710 | 19 | .BI "int getgrouplist(const char *" user ", gid_t " group , |
cc4615cc | 20 | .BI " gid_t *" groups ", int *" ngroups ); |
c7db92b9 | 21 | .fi |
68e4db0a | 22 | .PP |
d39ad78f | 23 | .RS -4 |
cc4615cc MK |
24 | Feature Test Macro Requirements for glibc (see |
25 | .BR feature_test_macros (7)): | |
d39ad78f | 26 | .RE |
68e4db0a | 27 | .PP |
cc4615cc | 28 | .BR getgrouplist (): |
9d281e06 | 29 | .nf |
51c612fb MK |
30 | Since glibc 2.19: |
31 | _DEFAULT_SOURCE | |
32 | Glibc 2.19 and earlier: | |
33 | _BSD_SOURCE | |
9d281e06 | 34 | .fi |
fea681da | 35 | .SH DESCRIPTION |
c13182ef | 36 | The |
63aa9df0 | 37 | .BR getgrouplist () |
307b4a04 MK |
38 | function scans the group database (see |
39 | .BR group (5)) | |
40 | to obtain the list of groups that | |
fea681da | 41 | .I user |
c13182ef MK |
42 | belongs to. |
43 | Up to | |
bd9b2a9c | 44 | .I *ngroups |
307b4a04 MK |
45 | of these groups are returned in the array |
46 | .IR groups . | |
847e0d88 | 47 | .PP |
307b4a04 MK |
48 | If it was not among the groups defined for |
49 | .I user | |
50 | in the group database, then | |
fea681da | 51 | .I group |
307b4a04 MK |
52 | is included in the list of groups returned by |
53 | .BR getgrouplist (); | |
620792cf | 54 | typically this argument is specified as the group ID from |
307b4a04 MK |
55 | the password record for |
56 | .IR user . | |
847e0d88 | 57 | .PP |
307b4a04 MK |
58 | The |
59 | .I ngroups | |
60 | argument is a value-result argument: | |
61 | on return it always contains the number of groups found for | |
62 | .IR user , | |
63 | including | |
64 | .IR group ; | |
65 | this value may be greater than the number of groups stored in | |
66 | .IR groups . | |
47297adb | 67 | .SH RETURN VALUE |
307b4a04 MK |
68 | If the number of groups of which |
69 | .I user | |
70 | is a member is less than or equal to | |
71 | .IR *ngroups , | |
72 | then the value | |
bd9b2a9c | 73 | .I *ngroups |
307b4a04 | 74 | is returned. |
847e0d88 | 75 | .PP |
307b4a04 MK |
76 | If the user is a member of more than |
77 | .I *ngroups | |
78 | groups, then | |
63aa9df0 | 79 | .BR getgrouplist () |
2b0fa182 | 80 | returns \-1. |
1e8fdbd9 | 81 | In this case, the value returned in |
1ae6b2c7 | 82 | .I *ngroups |
a1692d75 | 83 | can be used to resize the buffer passed to a further call to |
307b4a04 | 84 | .BR getgrouplist (). |
47297adb | 85 | .SH VERSIONS |
2b2581ee | 86 | This function is present since glibc 2.2.4. |
39e22958 PH |
87 | .SH ATTRIBUTES |
88 | For an explanation of the terms used in this section, see | |
89 | .BR attributes (7). | |
c466875e MK |
90 | .ad l |
91 | .nh | |
39e22958 PH |
92 | .TS |
93 | allbox; | |
c466875e | 94 | lbx lb lb |
39e22958 PH |
95 | l l l. |
96 | Interface Attribute Value | |
97 | T{ | |
98 | .BR getgrouplist () | |
99 | T} Thread safety MT-Safe locale | |
100 | .TE | |
c466875e MK |
101 | .hy |
102 | .ad | |
103 | .sp 1 | |
47297adb | 104 | .SH CONFORMING TO |
c8f2dd47 | 105 | This function is nonstandard; it appears on most BSDs. |
fea681da | 106 | .SH BUGS |
307b4a04 MK |
107 | In glibc versions before 2.3.3, |
108 | the implementation of this function contains a buffer-overrun bug: | |
109 | it returns the complete list of groups for | |
1ae6b2c7 | 110 | .I user |
307b4a04 MK |
111 | in the array |
112 | .IR groups , | |
113 | even when the number of groups exceeds | |
bd9b2a9c | 114 | .IR *ngroups . |
a14af333 | 115 | .SH EXAMPLES |
307b4a04 MK |
116 | The program below displays the group list for the user named in its |
117 | first command-line argument. | |
118 | The second command-line argument specifies the | |
119 | .I ngroups | |
120 | value to be supplied to | |
85ea9716 | 121 | .BR getgrouplist (). |
307b4a04 | 122 | The following shell session shows examples of the use of this program: |
e646a1ba | 123 | .PP |
307b4a04 | 124 | .in +4n |
e646a1ba | 125 | .EX |
b43a3b30 | 126 | .RB "$" " ./a.out cecilia 0" |
c3074d70 | 127 | getgrouplist() returned \-1; ngroups = 3 |
b43a3b30 | 128 | .RB "$" " ./a.out cecilia 3" |
307b4a04 MK |
129 | ngroups = 3 |
130 | 16 (dialout) | |
131 | 33 (video) | |
132 | 100 (users) | |
b8302363 | 133 | .EE |
307b4a04 | 134 | .in |
9c330504 | 135 | .SS Program source |
d84d0300 | 136 | \& |
e7d0bb47 | 137 | .EX |
fea681da MK |
138 | #include <stdio.h> |
139 | #include <stdlib.h> | |
140 | #include <grp.h> | |
141 | #include <pwd.h> | |
142 | ||
c13182ef | 143 | int |
307b4a04 | 144 | main(int argc, char *argv[]) |
cf0a9ace | 145 | { |
88893a77 | 146 | int ngroups; |
307b4a04 MK |
147 | struct passwd *pw; |
148 | struct group *gr; | |
c59aa7fc | 149 | gid_t *groups; |
307b4a04 MK |
150 | |
151 | if (argc != 3) { | |
d1a71985 | 152 | fprintf(stderr, "Usage: %s <user> <ngroups>\en", argv[0]); |
307b4a04 MK |
153 | exit(EXIT_FAILURE); |
154 | } | |
fea681da | 155 | |
00ac6ce4 | 156 | ngroups = atoi(argv[2]); |
307b4a04 | 157 | |
c59aa7fc | 158 | groups = malloc(sizeof(*groups) * ngroups); |
307b4a04 MK |
159 | if (groups == NULL) { |
160 | perror("malloc"); | |
161 | exit(EXIT_FAILURE); | |
162 | } | |
163 | ||
46b20ca1 | 164 | /* Fetch passwd structure (contains first group ID for user). */ |
307b4a04 MK |
165 | |
166 | pw = getpwnam(argv[1]); | |
167 | if (pw == NULL) { | |
168 | perror("getpwnam"); | |
5bc8c34c | 169 | exit(EXIT_SUCCESS); |
307b4a04 MK |
170 | } |
171 | ||
46b20ca1 | 172 | /* Retrieve group list. */ |
fea681da | 173 | |
307b4a04 | 174 | if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) { |
d1a71985 | 175 | fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\en", |
307b4a04 | 176 | ngroups); |
5a6194a4 | 177 | exit(EXIT_FAILURE); |
cf0a9ace | 178 | } |
fea681da | 179 | |
46b20ca1 | 180 | /* Display list of retrieved groups, along with group names. */ |
307b4a04 | 181 | |
d1a71985 | 182 | fprintf(stderr, "ngroups = %d\en", ngroups); |
88893a77 | 183 | for (int j = 0; j < ngroups; j++) { |
307b4a04 MK |
184 | printf("%d", groups[j]); |
185 | gr = getgrgid(groups[j]); | |
186 | if (gr != NULL) | |
187 | printf(" (%s)", gr\->gr_name); | |
d1a71985 | 188 | printf("\en"); |
00ac6ce4 | 189 | } |
cf0a9ace | 190 | |
5bc8c34c | 191 | exit(EXIT_SUCCESS); |
fea681da | 192 | } |
e7d0bb47 | 193 | .EE |
47297adb | 194 | .SH SEE ALSO |
f56f5b89 | 195 | .BR getgroups (2), |
307b4a04 MK |
196 | .BR setgroups (2), |
197 | .BR getgrent (3), | |
94ed3bb9 | 198 | .BR group_member (3), |
5744079a MK |
199 | .BR group (5), |
200 | .BR passwd (5) |