.\"- .\" 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 .\" 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 .