.\"-
.\" 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.
.\"
.\"     @(#)getgroups.2	8.2 (Berkeley) 4/16/94
.\"
.Dd October 10, 2025
.Dt GETGROUPS 2
.Os
.Sh NAME
.Nm getgroups
.Nd get the calling process' effective groups
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn getgroups "int gidsetlen" "gid_t *gidset"
.Sh DESCRIPTION
The
.Fn getgroups
system call retrieves the calling process' effective groups, i.e., the effective
group ID and the supplementary groups, and stores them in the
.Fa gidset
array.
The value of
.Fa gidsetlen
indicates the maximum number of entries that may be placed in
.Fa gidset .
.Pp
If the value of
.Fa gidsetlen
is large enough, the effective group ID is stored in the first slot
.Pq Va gidset[0]
and the supplementary groups in subsequent ones in strictly ascending order.
If
.Fa gidsetlen
is zero,
.Fn getgroups
returns one more than the cardinal of the calling process' supplementary groups
set and ignores argument
.Fa gidset .
.Pp
No more than
.Dv {NGROUPS_MAX}+1
values may ever be returned.
The value of
.Dv {NGROUPS_MAX}
should be obtained using
.Xr sysconf 3
to avoid hard-coding it into the executable.
.Sh RETURN VALUES
On success, the
.Fn getgroups
system call returns one more than the cardinal of the supplementary groups set.
It always succeeds if argument
.Fa gidsetlen
is zero.
.Pp
A value of -1 indicates that an error occurred, and the error
code is stored in the global variable
.Va errno .
.Sh ERRORS
The possible errors for
.Fn getgroups
are:
.Bl -tag -width Er
.It Bq Er EINVAL
The argument
.Fa gidsetlen
is smaller than the number of supplementary groups plus one
.Pq but not zero .
.It Bq Er EFAULT
An invalid address was encountered while reading from the
.Fa gidset
array.
.El
.Sh SEE ALSO
.Xr setgroups 2 ,
.Xr initgroups 3 ,
.Xr sysconf 3
.Sh STANDARDS
The
.Fn getgroups
system call conforms to
.St -p1003.1-2008 ,
returning the effective group ID along with supplementary groups.
.Sh HISTORY
The
.Fn getgroups
system call appeared in
.Bx 4.2 .
.Pp
Since
.Fx 14.3 ,
the
.Fn getgroups
system call has been reporting the supplementary groups in strictly ascending
order.
.Pp
Starting with
.Fx 15 ,
the
.Fn getgroups
system call will change semantics.
It will return only the supplementary groups, and not the effective group ID
anymore.
.Sh SECURITY CONSIDERATIONS
On success, the group IDs reported in
.Fa gidset
are unique except that the effective group ID in the first slot may be
duplicated in another slot if it is also included in the supplementary groups.
.Pp
Starting with
.Fx 15 ,
the
.Fn getgroups
system call will stop reporting the effective group ID as the first slot of the
.Fa gidset
array.
Programs that process this slot in a specific way will need to be modified to
obtain the effective group ID through other means, such as a call to
.Xr getegid 2 .