1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
.\"-
.\" SPDX-License-Identifier: BSD-3-Clause
.\"
.\" Copyright (c) 1983, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
.\" Copyright (c) 2025 The FreeBSD Foundation
.\"
.\" Portions of this documentation were written by Olivier Certner
.\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the FreeBSD
.\" Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd September 17, 2025
.Dt SETGROUPS 2
.Os
.Sh NAME
.Nm setgroups
.Nd set the calling process' supplementary groups
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/param.h
.In unistd.h
.Ft int
.Fn setgroups "int ngroups" "const gid_t *gidset"
.Sh DESCRIPTION
The
.Fn setgroups
system call sets the calling process' supplementary groups according to the
.Fa gidset
array.
The
.Fa ngroups
argument indicates the number of entries in the array and must be no more than
.Dv {NGROUPS_MAX} .
.Pp
The
.Fa ngroups
argument may be set to zero to clear all supplementary groups, in which case
.Fa gidset
is ignored.
.Pp
Only the super-user may install a new supplementary groups set.
.Sh RETURN VALUES
.Rv -std setgroups
.Sh ERRORS
The
.Fn setgroups
system call will fail if:
.Bl -tag -width Er
.It Bq Er EPERM
The caller is not the super-user.
.It Bq Er EINVAL
The number specified in the
.Fa ngroups
argument is larger than the
.Dv {NGROUPS_MAX}
limit.
.It Bq Er EFAULT
Part of the groups array starting at
.Fa gidset
is outside the process address space.
.El
.Sh SEE ALSO
.Xr getgroups 2 ,
.Xr setcred 2 ,
.Xr initgroups 3
.Sh HISTORY
The
.Fn setgroups
system call appeared in
.Bx 4.2 .
.Pp
Before
.Fx 15.0 ,
the
.Fn setgroups
system call would set the effective group ID for the process to the first
element of
.Fa gidset ,
and only the other elements as supplementary groups.
Despite treating the first element as the effective group ID to set, it accepted
an empty
.Fa gidset
.Po
.Fa ngroups
being zero
.Pc
as a stance requiring to drop all supplementary groups, leaving the effective
group ID unchanged.
.Sh SECURITY CONSIDERATIONS
The
.Fn setgroups
system call sets the process' supplementary groups to those contained in the
.Fa gidset
array.
In particular, as evoked in
.Sx HISTORY ,
it does not anymore treat the first element of
.Fa gidset
separately.
Formerly, it would set it as the effective group ID while only the others were
used as supplementary groups.
.Pp
Programs solely relying on
.Fn setgroups
to change the effective group ID must be modified, e.g., to also call
.Xr setegid 2
or to instead use
.Xr setcred 2 ,
else they will unwillingly keep their effective group ID.
.Pp
Programs using
.Fn setgroups
with the effective group ID as the first element of array
.Fa gidset
and not duplicating it in the rest of the array, which includes those using
.Fn initgroups ,
now insert this group ID in the supplementary groups set.
This is in general desirable, as explained in the
.Xr initgroups 3
manual page, and has the consequence that subsequent process' effective group
ID's changes do not remove membership of the original effective group ID, since
these changes do not affect the supplementary groups.
Applications that expressly do not want that must be modified to stop passing
the effective group ID as the first element to
.Fn setgroups .
.Pp
To clear all the calling process' supplementary groups, always use the statement
.Bd -literal -offset indent
setgroups(0, NULL);
.Ed
.Pp
which works also on older FreeBSD version
.Po
see the
.Sx HISTORY
section
.Pc .
|
