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