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