'\"macro stdmacro
.if n .pH g2.getgroups @(#)getgroups	41.4 of 5/26/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 AT&T
.nr X
.if \nX=0 .ds x} getgroups 2 "" "\&"
.if \nX=1 .ds x} getgroups 2 ""
.if \nX=2 .ds x} getgroups 2 "" "\&"
.if \nX=3 .ds x} getgroups "" "" "\&"
.TH \*(x}
.SH NAME
\f4getgroups\f1 \- get supplementary group access list \s-1ID\s0s
.SH SYNOPSIS
\f4#include <unistd.h>\f1
.PP
.ft 3
int ngrps;
.PP
.ti -2
.SM
.IR POSIX :
.br
.B
ngrps = getgroups(int setlen, gid_t *gidset);
.PP
.ti -2
.SM
.IR BSD :
.br
.B
ngrps = getgroups(int setlen, int *gidset);
.fi
.PP
To use the
.SM BSD
version of
.IR getgroups
one must either
.IP 1) 3
explicitly invoke it as
.IR BSDgetgroups
or
.IP 2) 3
link with the libbsd.a library:
.Ex
cc -o prog prog.c -lbsd
.Ee
.SH DESCRIPTION
.I getgroups
retrieves the current group access list of the user process
and stores it in the array
.IR gidset .
The parameter
.I setlen
indicates the number of entries that may be placed in
.IR gidset.
The return value is the actual number of groups placed in
.IR gidset ,
and this will never be greater than 
.SM
.BR NGROUPS_UMAX
for the
.SM POSIX
version, and 
.SM
.BR NGROUPS
for the 
.SM BSD
version, as defined in
.RI < sys/param.h >.
.PP
As a special case, if the
.I setlen
parameter is zero,
.I getgroups
returns the number of supplemental group \s-1ID\s+1s associated with the
calling process without modifying the array pointed to by the
.I gidset
argument.
.SH "RETURN VALUE
A successful call returns the number of groups in the group set.
A value of \-1 indicates that an error occurred, and the error
code is stored in the global variable 
.IR errno .
.SH "ERRORS
The possible errors for 
.I getgroups
are:
.TP 15
.SM
\%[EINVAL]
The argument
.I setlen
is smaller than the number of groups in the group set.
.TP
.SM
\%[EFAULT]
The argument 
.I gidset
specifies an invalid address.
.SH "SEE ALSO
multgrps(1), setgroups(2), initgroups(3)
.SH CAVEATS
The POSIX and 4.3BSD versions differ
in the types of their
.I gidset
parameter.