Debian Codegraph @

upstream/debian-unstable/man2/getgroups.2

raw
1 .\" Copyright 1993, Rickard E. Faith <[email protected]>
2 .\" Copyright 2008-2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getgroups 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getgroups, setgroups \- get/set list of supplementary group IDs
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int getgroups(int " size ", gid_t " list "[_Nullable " size ]);
18 .P
19 .B #include <grp.h>
20 .P
21 .BI "int setgroups(size_t " size ", const gid_t " list [ size ]);
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 setgroups ():
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 .BR getgroups ()
38 returns the supplementary group IDs of the calling process in
39 .IR list .
40 The argument
41 .I size
42 should be set to the maximum number of items that can be stored in the
43 buffer pointed to by
44 .IR list .
45 If the calling process is a member of more than
46 .I size
47 supplementary groups, then an error results.
48 .P
49 It is unspecified whether the effective group ID of the calling process
50 is included in the returned list.
51 (Thus, an application should also call
52 .BR getegid (2)
53 and add or remove the resulting value.)
54 .P
55 If
56 .I size
57 is zero,
58 .I list
59 is not modified, but the total number of supplementary group IDs for the
60 process is returned.
61 This allows the caller to determine the size of a dynamically allocated
62 .I list
63 to be used in a further call to
64 .BR getgroups ().
65 .P
66 .BR setgroups ()
67 sets the supplementary group IDs for the calling process.
68 Appropriate privileges are required (see the description of the
69 .B EPERM
70 error, below).
71 The
72 .I size
73 argument specifies the number of supplementary group IDs
74 in the buffer pointed to by
75 .IR list .
76 A process can drop all of its supplementary groups with the call:
77 .P
78 .in +4n
79 .EX
80 setgroups(0, (gid_t [0]){});
81 .EE
82 .in
83 .SH RETURN VALUE
84 On success,
85 .BR getgroups ()
86 returns the number of supplementary group IDs.
87 On error, \-1 is returned, and
88 .I errno
89 is set to indicate the error.
90 .P
91 On success,
92 .BR setgroups ()
93 returns 0.
94 On error, \-1 is returned, and
95 .I errno
96 is set to indicate the error.
97 .SH ERRORS
98 .TP
99 .B EFAULT
100 .I list
101 has an invalid address.
102 .P
103 .BR getgroups ()
104 can additionally fail with the following error:
105 .TP
106 .B EINVAL
107 .I size
108 is less than the number of supplementary group IDs, but is not zero.
109 .P
110 .BR setgroups ()
111 can additionally fail with the following errors:
112 .TP
113 .B EINVAL
114 .I size
115 is greater than
116 .B NGROUPS_MAX
117 (32 before Linux 2.6.4;
118 65536 since Linux 2.6.4).
119 .TP
120 .B ENOMEM
121 Out of memory.
122 .TP
123 .B EPERM
124 The calling process has insufficient privilege
125 (the caller does not have the
126 .B CAP_SETGID
127 capability in the user namespace in which it resides).
128 .TP
129 .BR EPERM " (since Linux 3.19)"
130 The use of
131 .BR setgroups ()
132 is denied in this user namespace.
133 See the description of
134 .IR /proc/ pid /setgroups
135 in
136 .BR user_namespaces (7).
137 .SH VERSIONS
138 .SS C library/kernel differences
139 At the kernel level, user IDs and group IDs are a per-thread attribute.
140 However, POSIX requires that all threads in a process
141 share the same credentials.
142 The NPTL threading implementation handles the POSIX requirements by
143 providing wrapper functions for
144 the various system calls that change process UIDs and GIDs.
145 These wrapper functions (including the one for
146 .BR setgroups ())
147 employ a signal-based technique to ensure
148 that when one thread changes credentials,
149 all of the other threads in the process also change their credentials.
150 For details, see
151 .BR nptl (7).
152 .SH STANDARDS
153 .TP
154 .BR getgroups ()
155 POSIX.1-2024.
156 .TP
157 .BR setgroups ()
158 None.
159 .SH HISTORY
160 .TP
161 .BR getgroups ()
162 4.3BSD,
163 SVr4,
164 POSIX.1-1988.
165 .TP
166 .BR setgroups ()
167 SVr4, 4.3BSD.
168 Since
169 .BR setgroups ()
170 requires privilege, it is not covered by POSIX.1.
171 .P
172 The original Linux
173 .BR getgroups ()
174 system call supported only 16-bit group IDs.
175 Subsequently, Linux 2.4 added
176 .BR getgroups32 (),
177 supporting 32-bit IDs.
178 The glibc
179 .BR getgroups ()
180 wrapper function transparently deals with the variation across kernel versions.
181 .SH NOTES
182 A process can have up to
183 .B NGROUPS_MAX
184 supplementary group IDs
185 in addition to the effective group ID.
186 The constant
187 .B NGROUPS_MAX
188 is defined in
189 .IR <limits.h> .
190 The set of supplementary group IDs
191 is inherited from the parent process, and preserved across an
192 .BR execve (2).
193 .P
194 The maximum number of supplementary group IDs can be found at run time using
195 .BR sysconf (3):
196 .P
197 .in +4n
198 .EX
199 long ngroups_max;
200 ngroups_max = sysconf(_SC_NGROUPS_MAX);
201 .EE
202 .in
203 .P
204 The maximum return value of
205 .BR getgroups ()
206 cannot be larger than one more than this value.
207 Since Linux 2.6.4, the maximum number of supplementary group IDs is also
208 exposed via the Linux-specific read-only file,
209 .IR /proc/sys/kernel/ngroups_max .
210 .SH EXAMPLES
211 .\" SRC BEGIN (agetgroups.c)
212 .EX
213 #include <err.h>
214 #include <stddef.h>
215 #include <stdint.h>
216 #include <stdio.h>
217 #include <stdlib.h>
218 #include <sys/types.h>
219 #include <unistd.h>
220 \&
221 #define MALLOC(n, T) ((T *) reallocarray(NULL, n, sizeof(T)))
222 \&
223 static gid_t *agetgroups(size_t *ngids);
224 \&
225 int
226 main(void)
227 {
228 gid_t *gids;
229 size_t n;
230 \&
231 gids = agetgroups(&n);
232 if (gids == NULL)
233 err(EXIT_FAILURE, "agetgroups");
234 \&
235 if (n != 0) {
236 printf("%jd", (intmax_t) gids[0]);
237 for (size_t i = 1; i < n; i++)
238 printf(" %jd", (intmax_t) gids[i]);
239 }
240 puts("");
241 \&
242 free(gids);
243 exit(EXIT_SUCCESS);
244 }
245 \&
246 static gid_t *
247 agetgroups(size_t *ngids)
248 {
249 int n;
250 gid_t *gids;
251 \&
252 n = getgroups(0, NULL);
253 if (n == \-1)
254 return NULL;
255 \&
256 gids = MALLOC(n, gid_t);
257 if (gids == NULL)
258 return NULL;
259 \&
260 n = getgroups(n, gids);
261 if (n == \-1) {
262 free(gids);
263 return NULL;
264 }
265 \&
266 *ngids = n;
267 return gids;
268 }
269 .EE
270 .\" SRC END
271 .SH SEE ALSO
272 .BR getgid (2),
273 .BR setgid (2),
274 .BR getgrouplist (3),
275 .BR group_member (3),
276 .BR initgroups (3),
277 .BR capabilities (7),
278 .BR credentials (7)