initgroups(3c)

NAME
     initgroups - initialize group access list

SYNOPSIS
   POSIX:
     #include <sys/types.h>

     int initgroups(char *name, gid_t basegid);

   BSD:

     int BSDinitgroups(char *name, int basegid);

DESCRIPTION
     initgroups and BSDinitgroups read through the group file (/etc/group) and
     set up, using the appropriate version of the setgroups call, the group
     access list for the user specified in name.  The basegid is automatically
     included in the groups list.  Typically this value is the group number
     from the password file.

     The difference between initgroups and BSDinitgroups is the type of the
     basegid parameter.  Both of these routines use the
     sysconf(_SC_NGROUPS_MAX) system call to determine the maximum number of
     groups at run-time.

FILES
     /etc/group
     /etc/passwd

SEE ALSO
     multgrps(1), getgroups(2), setgroups(2), sysconf(3C)

DIAGNOSTICS
     initgroups returns 0 if successful.  If the calling routine doesn't have
     superuser privileges, it returns -1 and an error code is stored in global
     integer errno.  If the specified user is a member of too many groups, the
     process is initialized with the maximum-allowed groups: the remaining
     groups are silently discarded by the system.  A special situation occurs
     when initgroups is called on systems with multiple groups disabled (i.e.,
     ngroups_max in </var/sysgen/master.d/kernel> set to 0): in this case
     initgroups returns -1 and errno is set to EINVAL.

ERRORS
     The initgroups call will fail if:

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

     [EINVAL]       The multiple-group facility is disabled on the system.
BUGS
     initgroups uses the routines based on getgrent(3).  If the invoking
     program uses any of these routines, the group structure will be
     overwritten in the call to initgroups.