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.