Debian Codegraph @

upstream/debian-trixie/man2/getgroups.2

raw
1 .\" Copyright 1993 Rickard E. Faith ([email protected])
2 .\" and Copyright (C) 2008, 2010, 2015, Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond <[email protected]>
7 .\" Modified, 27 May 2004, Michael Kerrisk <[email protected]>
8 .\" Added notes on capability requirements
9 .\" 2008-05-03, mtk, expanded and rewrote parts of DESCRIPTION and RETURN
10 .\" VALUE, made style of page more consistent with man-pages style.
11 .\"
12 .TH getgroups 2 2024-05-02 "Linux man-pages 6.9.1"
13 .SH NAME
14 getgroups, setgroups \- get/set list of supplementary group IDs
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <unistd.h>
21 .P
22 .BI "int getgroups(int " size ", gid_t " list []);
23 .P
24 .B #include <grp.h>
25 .P
26 .BI "int setgroups(size_t " size ", const gid_t *_Nullable " list );
27 .fi
28 .P
29 .RS -4
30 Feature Test Macro Requirements for glibc (see
31 .BR feature_test_macros (7)):
32 .RE
33 .P
34 .BR setgroups ():
35 .nf
36 Since glibc 2.19:
37 _DEFAULT_SOURCE
38 glibc 2.19 and earlier:
39 _BSD_SOURCE
40 .fi
41 .SH DESCRIPTION
42 .BR getgroups ()
43 returns the supplementary group IDs of the calling process in
44 .IR list .
45 The argument
46 .I size
47 should be set to the maximum number of items that can be stored in the
48 buffer pointed to by
49 .IR list .
50 If the calling process is a member of more than
51 .I size
52 supplementary groups, then an error results.
53 .P
54 It is unspecified whether the effective group ID of the calling process
55 is included in the returned list.
56 (Thus, an application should also call
57 .BR getegid (2)
58 and add or remove the resulting value.)
59 .P
60 If
61 .I size
62 is zero,
63 .I list
64 is not modified, but the total number of supplementary group IDs for the
65 process is returned.
66 This allows the caller to determine the size of a dynamically allocated
67 .I list
68 to be used in a further call to
69 .BR getgroups ().
70 .P
71 .BR setgroups ()
72 sets the supplementary group IDs for the calling process.
73 Appropriate privileges are required (see the description of the
74 .B EPERM
75 error, below).
76 The
77 .I size
78 argument specifies the number of supplementary group IDs
79 in the buffer pointed to by
80 .IR list .
81 A process can drop all of its supplementary groups with the call:
82 .P
83 .in +4n
84 .EX
85 setgroups(0, NULL);
86 .EE
87 .in
88 .SH RETURN VALUE
89 On success,
90 .BR getgroups ()
91 returns the number of supplementary group IDs.
92 On error, \-1 is returned, and
93 .I errno
94 is set to indicate the error.
95 .P
96 On success,
97 .BR setgroups ()
98 returns 0.
99 On error, \-1 is returned, and
100 .I errno
101 is set to indicate the error.
102 .SH ERRORS
103 .TP
104 .B EFAULT
105 .I list
106 has an invalid address.
107 .P
108 .BR getgroups ()
109 can additionally fail with the following error:
110 .TP
111 .B EINVAL
112 .I size
113 is less than the number of supplementary group IDs, but is not zero.
114 .P
115 .BR setgroups ()
116 can additionally fail with the following errors:
117 .TP
118 .B EINVAL
119 .I size
120 is greater than
121 .B NGROUPS_MAX
122 (32 before Linux 2.6.4; 65536 since Linux 2.6.4).
123 .TP
124 .B ENOMEM
125 Out of memory.
126 .TP
127 .B EPERM
128 The calling process has insufficient privilege
129 (the caller does not have the
130 .B CAP_SETGID
131 capability in the user namespace in which it resides).
132 .TP
133 .BR EPERM " (since Linux 3.19)"
134 The use of
135 .BR setgroups ()
136 is denied in this user namespace.
137 See the description of
138 .IR /proc/ pid /setgroups
139 in
140 .BR user_namespaces (7).
141 .SH VERSIONS
142 .SS C library/kernel differences
143 At the kernel level, user IDs and group IDs are a per-thread attribute.
144 However, POSIX requires that all threads in a process
145 share the same credentials.
146 The NPTL threading implementation handles the POSIX requirements by
147 providing wrapper functions for
148 the various system calls that change process UIDs and GIDs.
149 These wrapper functions (including the one for
150 .BR setgroups ())
151 employ a signal-based technique to ensure
152 that when one thread changes credentials,
153 all of the other threads in the process also change their credentials.
154 For details, see
155 .BR nptl (7).
156 .SH STANDARDS
157 .TP
158 .BR getgroups ()
159 POSIX.1-2008.
160 .TP
161 .BR setgroups ()
162 None.
163 .SH HISTORY
164 .TP
165 .BR getgroups ()
166 SVr4, 4.3BSD, POSIX.1-2001.
167 .TP
168 .BR setgroups ()
169 SVr4, 4.3BSD.
170 Since
171 .BR setgroups ()
172 requires privilege, it is not covered by POSIX.1.
173 .P
174 The original Linux
175 .BR getgroups ()
176 system call supported only 16-bit group IDs.
177 Subsequently, Linux 2.4 added
178 .BR getgroups32 (),
179 supporting 32-bit IDs.
180 The glibc
181 .BR getgroups ()
182 wrapper function transparently deals with the variation across kernel versions.
183 .SH NOTES
184 A process can have up to
185 .B NGROUPS_MAX
186 supplementary group IDs
187 in addition to the effective group ID.
188 The constant
189 .B NGROUPS_MAX
190 is defined in
191 .IR <limits.h> .
192 The set of supplementary group IDs
193 is inherited from the parent process, and preserved across an
194 .BR execve (2).
195 .P
196 The maximum number of supplementary group IDs can be found at run time using
197 .BR sysconf (3):
198 .P
199 .in +4n
200 .EX
201 long ngroups_max;
202 ngroups_max = sysconf(_SC_NGROUPS_MAX);
203 .EE
204 .in
205 .P
206 The maximum return value of
207 .BR getgroups ()
208 cannot be larger than one more than this value.
209 Since Linux 2.6.4, the maximum number of supplementary group IDs is also
210 exposed via the Linux-specific read-only file,
211 .IR /proc/sys/kernel/ngroups_max .
212 .SH SEE ALSO
213 .BR getgid (2),
214 .BR setgid (2),
215 .BR getgrouplist (3),
216 .BR group_member (3),
217 .BR initgroups (3),
218 .BR capabilities (7),
219 .BR credentials (7)