getgroups2
Get the calling process' supplementary groups
Usage
#include <unistd.h>
int
getgroups(int gidsetlen, gid_t *gidset);
Library
Standard C Library (libc, -lc)
Overview
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.
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.
Releases
87 releases since FreeBSD 2.0.5-RELEASE; the text changed 44 times.