.TH initgroups() "" "" "General Function (libc)"
.PC "Initialize the supplementary group-access list"
.B "#include <sys/types.h>"
.B "#include <grp.h>"
\fBint initgroups(\fIuser\^\fB, \fIbasegid\^\fB)\fR
\fBconst char *\fIuser\^\fB; gid_t \fIbasegid\^\fB;\fR
.PP
The ``supplemental group-access list''
is the list of group identifiers that are used in addition
to the effective group
identifier when determining the level of access that a process has to a file.
The function
.B initgroups()
initializes the supplemental group-access list to the groups to which
.I user
belongs.
.PP
.I user
is the login identifier of the user in question.
.I basegid
identifies that user's base group, as set in the file
.BR /etc/passwd .
.B initgroups()
calls the library function
.B getgrent()
to read from
.B /etc/group
all of the groups to which
.I user
belongs (in addition to her base group).
It then calls
.B setgroups()
to initialize the supplementary group-access list to
.IR user 's
base group and the additional groups returned by
.BR getgrent() .
.PP
If all goes well,
.B initgroups()
modifies the supplementary group-access list returns zero.
Otherwise, it does not modify the list, returns \-1, and sets
.B errno
to an appropriate value.
.SH "See Also"
.Xr "getgrent()," getgrent
.Xr "libc," libc
.Xr "setgroups()" setgroups
.SH Notes
If
.I user
belongs to more than
.B NGROUPS_MAX
groups,
.B initgroups()
reads only the first
.B NGROUPS_MAX
groups from
.B /etc/group
and ignores all of the others.
Note that
.B NGROUPS_MAX
is a limit set by the \*(PX.
For a fuller discussion of these limits, see the Lexicon entries for
.B sysconf()
and
.BR limits.h .
.PP
Only the superuser
.B root
can use
.BR initgroups() .
