.TH getgroups() "" "" "System Call (libc)"
.PC "Read the supplemental group-access list"
.B "#include <unistd.h>"
\fBint getgroups(\fIgidsetsize\^\fB, \fIgrouplist\^\fB)\fR
\fBint \fIgidsetsize\^\fB; gid_t *\fIgrouplist\^\fB;\fR
.PP
.II "supplemental group-access list"
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.
.B getgroups()
reads the identifiers from the current process's supplemental group-access
list,
and writes them into the array to which
.I grouplist
points.
.PP
.I grouplist
has
.I gidsetsize
entries, and must be large enough to contain every entry from the list.
The list cannot have more than
.B NGROUPS_MAX
entries.
If
.I gidsetsize
equals zero,
.BR getgroups()
returns the number of groups to which the calling process belongs
without modifying the array to which
.I grouplist
points.
.PP
If all goes well,
.B getgroups()
returns the number of supplementary-group identifiers
set for the calling process.
It fails and returns \-1 if
.I gidsetsize
is greater than zero but
less than the number of supplementary-group identifiers set for the
calling process, or if
.I grouplist
points to an illegal address.
In the former instance, it sets
.B errno
to
.BR EINVAL ;
in the latter, it sets
.B errno
to
.BR EFAULT .
.SH "See Also"
.Xr "libc," libc
.Xr "setgroups()," setgroups
.Xr "unistd.h" unistd.h
.br
\*(PX Standard, \(sc4.2.3
