.\"-
.\" 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.
.\"
.Dd October 10, 2025
.Dt GETGROUPS 2
.Os
.Sh NAME
.Nm getgroups
.Nd get the calling process' supplementary 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 gets the calling process' supplementary groups and stores them in
the
.Fa gidset
array in strictly ascending order.
The value of
.Fa gidsetlen
indicates the maximum number of entries that may be placed in
.Fa gidset .
.Pp
If
.Fa gidsetlen
is zero,
.Fn getgroups
returns the cardinal of the calling process' supplementary groups set and
ignores argument
.Fa gidset .
.Pp
No more than
.Dv {NGROUPS_MAX}
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 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
.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 ,
not reporting the effective group ID.
.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
Before
.Fx 15.0 ,
the
.Fn getgroups
system call would additionally return the effective group ID as the first
element of the array, before the supplementary groups.
.Sh SECURITY CONSIDERATIONS
The
.Fn getgroups
system call gets the supplementary groups set in the
.Fa gidset
array.
In particular, as evoked in
.Sx HISTORY ,
it does not anymore retrieve the effective group ID in the first slot of
.Fa gidset .
Programs that process this slot in a specific way must be modified to obtain the
effective group ID through other means, such as a call to
.Xr getegid 2 .
.Pp
The effective group ID is present in the supplementary groups set if and only if
it was explicitly set as a supplementary group.
The function
.Fn initgroups
enforces that, while the
.Fn setgroups
system call does not.
Please consult the
.Xr initgroups 3
manual page for the rationale.