FreeBSD Manual Pages
GETGROUPS(2) 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 re- turn 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 any- more retrieve the effective group ID in the first slot of gidset. Pro- grams that process this slot in a specific way must be modified to ob- tain 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 func- tion initgroups() enforces that, while the setgroups() system call does not. Please consult the initgroups(3) manual page for the rationale. FreeBSD 15.0 October 10, 2025 GETGROUPS(2)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | SECURITY CONSIDERATIONS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=getgroups&sektion=2&manpath=FreeBSD+15.0-RELEASE+and+Ports>