GETGROUPS(2)              FreeBSD System Calls Manual             GETGROUPS(2)

NAME

     getgroups - get the calling process' supplementary groups

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <unistd.h>

     int
     getgroups(int gidsetlen, gid_t *gidset);

DESCRIPTION

     The getgroups() system call gets the calling process' supplementary
     groups and stores them in the gidset array in strictly ascending order.
     The value of gidsetlen indicates the maximum number of entries that may
     be placed in gidset.

     If gidsetlen is zero, getgroups() returns the cardinal of the calling
     process' supplementary groups set and ignores argument gidset.

     No more than {NGROUPS_MAX} values may ever be returned.  The value of
     {NGROUPS_MAX} should be obtained using sysconf(3) to avoid hard-coding it
     into the executable.

RETURN VALUES

     On success, the getgroups() system call returns the cardinal of the
     supplementary groups set.  It always succeeds if argument gidsetlen is
     zero.

     A value of -1 indicates that an error occurred, and the error code is
     stored in the global variable errno.

ERRORS

     The possible errors for getgroups() are:

     [EINVAL]           The argument gidsetlen is smaller than the number of
                        supplementary groups (but not zero).

     [EFAULT]           An invalid address was encountered while reading from
                        the gidset array.

SEE ALSO

     setgroups(2), initgroups(3), sysconf(3)

STANDARDS

     The getgroups() system call conforms to IEEE Std 1003.1-2008 ("POSIX.1"),
     not reporting the effective group ID.

HISTORY

     The getgroups() system call appeared in 4.2BSD.

     Since FreeBSD 14.3, the getgroups() system call has been reporting the
     supplementary groups in strictly ascending order.

     Before FreeBSD 15.0, the getgroups() system call would additionally
     return the effective group ID as the first element of the array, before
     the supplementary groups.

SECURITY CONSIDERATIONS

     The getgroups() system call gets the supplementary groups set in the
     gidset array.  In particular, as evoked in HISTORY, it does not anymore
     retrieve the effective group ID in the first slot of 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 getegid(2).

     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
     initgroups() enforces that, while the setgroups() system call does not.
     Please consult the initgroups(3) manual page for the rationale.

FreeBSD 15.1-STABLE-HBSD       October 10, 2025                   GETGROUPS(2)