.\"-
.\" SPDX-License-Identifier: BSD-3-Clause
.\"
.\" Copyright (c) 1983, 1991, 1993
.\"	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.
.\"
.\"     @(#)initgroups.3	8.1 (Berkeley) 6/4/93
.\"
.Dd October 9, 2025
.Dt INITGROUPS 3
.Os
.Sh NAME
.Nm initgroups
.Nd initialize the effective groups using the group database
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn initgroups "const char *name" "gid_t basegid"
.Sh DESCRIPTION
The
.Fn initgroups
function initializes the current process' effective and supplementary groups,
collectively called the effective groups, as prescribed by its arguments and the
system's group database.
.Pp
It first uses the
.Fn getgrouplist
function to compute a list of groups containing the passed
.Fa basegid ,
which typically is the user's initial numerical group ID from the password
database, and the supplementary groups in the group database for the user named
.Fa name .
It then installs this list as the current process' effective groups using
.Fn setgroups .
.Sh RETURN VALUES
.Rv -std initgroups
.Sh ERRORS
The
.Fn initgroups
function may fail and set
.Va errno
to any of the errors specified for the
.Xr setgroups 2
system call, or to:
.Bl -tag -width Er
.It Bq Er ENOMEM
The
.Fn initgroups
function was unable to allocate temporary storage.
.El
.Sh SEE ALSO
.Xr setgroups 2 ,
.Xr getgrouplist 3
.Sh HISTORY
The
.Fn initgroups
function appeared in
.Bx 4.2 .
.Pp
The
.Fn initgroups
function has changed semantics in
.Fx 15 ,
following that of
.Xr setgroups 2
in the same release.
In the current version,
.Nm
sets the effective group ID to
.Fa basegid
and does not include the latter in the supplementary groups.
Starting with
.Fx 15 ,
.Nm
leaves the effective group ID unchanged and includes
.Fa basegid
in the supplementary groups instead.
.Sh SECURITY CONSIDERATIONS
.Nm
currently sets the effective group ID to
.Fa basegid .
Starting with
.Fx 15 ,
it will not do so anymore.
Programs that rely solely on
.Nm
to change the effective group ID will have to be modified.
For maximum compatibility, please make sure that some standard or traditional
function changing the effective group ID, such as
.Xr setgid 2
or
.Xr setegid 2 ,
is used in conjunction with
.Nm
.Pq this should always be the case for portable programs .
.Pp
Processes requesting a change of effective group ID or that are spawned from
executables with the set-group-ID mode bit set relinquish the access rights
deriving from being a member of their initial effective group ID, unless the
latter is also included in the supplementary groups.
Duplication of the effective group ID in the supplementary groups currently only
happens if the user's initial numerical group ID from the password database is
seconded by a corresponding group entry listing the user in the group database.
As, starting from
.Fx 15 ,
.Nm
will put
.Fa basegid
in the supplementary groups set, such additional entries in the group database
will become unnecessary.