| 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) |