GETGROUPS(2)

NAME
getgroups - get the calling process' effective groups

LIBRARY
libc

SYNOPSIS
#include <unistd.h>
int
getgroups(int gidsetlen, gid_t *gidset);

DESCRIPTION
The getgroups() system call retrieves the calling process' effective groups, i.e., the effective group ID and the supplementary groups, and stores them in the gidset array. The value of gidsetlen indicates the maximum number of entries that may be placed in gidset.

If the value of gidsetlen is large enough, the effective group ID is stored in the first slot (gidset[0]) and the supplementary groups in subsequent ones in strictly ascending order. If gidsetlen is zero, getgroups() returns one more than the cardinal of the calling process' supplementary groups set and ignores argument gidset.

No more than {NGROUPS_MAX}+1 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 one more than 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 plus one (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 p1003.1-2008, returning the effective group ID along with supplementary groups.

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.

Starting with FreeBSD 15, the getgroups() system call will change semantics. It will return only the supplementary groups, and not the effective group ID anymore.

SECURITY CONSIDERATIONS
On success, the group IDs reported in 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.

Starting with FreeBSD 15, the getgroups() system call will stop reporting the effective group ID as the first slot of the 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 getegid(2).