INITGROUPS(3)

NAME
initgroups - initialize the effective groups using the group database

LIBRARY
libc

SYNOPSIS
#include <unistd.h>
int
initgroups(const char *name, gid_t basegid);

DESCRIPTION
The initgroups() function initializes the current process' effective and supplementary groups, collectively called the effective groups, as prescribed by its arguments and the system's group database.

It first uses the getgrouplist() function to compute a list of groups containing the passed basegid, which typically is the user's initial numerical group ID from the password database, and the supplementary groups in the group database for the user named name. It then installs this list as the current process' effective groups using setgroups().

RETURN VALUES

ERRORS
The initgroups() function may fail and set errno to any of the errors specified for the setgroups(2) system call, or to:

[ENOMEM]
    The initgroups() function was unable to allocate temporary storage.

SEE ALSO
setgroups(2), getgrouplist(3)

HISTORY
The initgroups() function appeared in 4.2BSD.

The initgroups() function has changed semantics in FreeBSD 15, following that of setgroups(2) in the same release. In the current version, initgroups sets the effective group ID to basegid and does not include the latter in the supplementary groups. Starting with FreeBSD 15, initgroups leaves the effective group ID unchanged and includes basegid in the supplementary groups instead.

SECURITY CONSIDERATIONS
initgroups currently sets the effective group ID to basegid. Starting with FreeBSD 15, it will not do so anymore. Programs that rely solely on initgroups 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 initgroups (this should always be the case for portable programs).

Processes requesting a change of effective group ID or that are spawned from executables with the set-group-ID mode bit set relinquish the access rights deriving from being a member of their initial effective group ID, unless the latter is also included in the supplementary groups. Duplication of the effective group ID in the supplementary groups currently only happens if the user's initial numerical group ID from the password database is seconded by a corresponding group entry listing the user in the group database. As, starting from FreeBSD 15, initgroups will put basegid in the supplementary groups set, such additional entries in the group database will become unnecessary.