SETGROUPS(2)

NAME
setgroups - set the calling process' effective groups

LIBRARY
libc

SYNOPSIS
#include <sys/param.h>
#include <unistd.h>
int
setgroups(int ngroups, const gid_t *gidset);

DESCRIPTION
The setgroups() system call sets the calling process' effective group ID and supplementary groups according to the gidset array. The ngroups argument indicates the number of entries in the array and must be no more than {NGROUPS_MAX}+1.

The effective group ID of the calling process is set to the first entry of the gidset array (gidset[0]) if ngroups is not zero. The other entries are used to form the new supplementary groups set.

The ngroups argument may be set to zero, in which case gidset is ignored, the effective group ID remains unchanged and all supplementary groups are cleared.

Only the super-user may install new effective groups.

RETURN VALUES

ERRORS
The setgroups() system call will fail if:

[EPERM]
    The caller is not the super-user.

[EINVAL]
    The number specified in the ngroups argument is larger than the {NGROUPS_MAX}+1 limit.

[EFAULT]
    Part of the groups array starting at gidset is outside the process address space.

SEE ALSO
getgroups(2), setcred(2), initgroups(3)

HISTORY
The setgroups() system call appeared in 4.2BSD.

Starting with FreeBSD 15, the setgroups() system call will change semantics. It will not anymore change the effective group ID, but only the supplementary groups set, which will be formed from the whole gidset array.

SECURITY CONSIDERATIONS
The setgroups() system call currently sets the effective group ID to the first element of gidset. Starting with FreeBSD 15, it will not do so anymore. Programs that rely solely on setgroups() to change the effective group ID will have to be modified. For maximum compatibility, please make sure that some standard or traditional function changing the effective group ID, such as setgid(2) or setegid(2), is used in conjunction with setgroups() (this should always be the case for portable programs).

Processes using functions to change their effective group ID (via setgid(2) or similar) or that are spawned from executables with the set-group-ID mode bit set relinquish the access rights deriving from being a member of the initial effective group ID, unless this group ID is also included in the supplementary groups. As, starting with FreeBSD 15, setgroups() will include the first element of gidset in the supplementary groups as the others, programs passing the effective group ID in that slot will retain their former access rights in the above-mentioned scenario. This is in particular true for programs that use the initgroups(3) function.