'\"macro stdmacro
.TH SETGROUPS 2
.UC 5
.SH NAME
setgroups \- set group access list
.SH SYNOPSIS
.nf
.ft 3
#include <sys/param.h>
.PP
.ti -2
.SM
.IR POSIX :
.br
.B
int setgroups(int ngroups, gid_t \(**gidset);
.ti -2
.SM
.IR BSD :
.br
.B
int setgroups(int ngroups, int \(**gidset);
.fi
.PP
To use the
.SM BSD
version of
.IR setgroups ,
one must either
.IP 1) 3
explicitly invoke it as
.IR BSDsetgroups
or
.IP 2) 3
link with the libbsd.a library:
.Ex
cc -o prog prog.c -lbsd
.Ee
.SH DESCRIPTION
.I setgroups
initializes the group access list of the current user process
according to the array
.IR gidset .
The parameter
.I ngroups
indicates the number of entries in the array.
The
.I sysconf(\f3\s-1_SC_NGROUPS_MAX\s+1\fP)
system call may be used to determine at runtime the maximum
allowable value for
.I ngroups
in the particular kernel configuration (it is an lbootable
value (\f2ngroups_max\fP) which is declared in /var/sysgen/master.d/kernel).
If using the
.SM BSD
version, 
.I ngroups
may never be greater than
.SM
.BR NGROUPS
(as defined in
<\f2sys/param.h\fP>).
.PP
Setting \f2ngroups_max\fP to zero and rebooting effectively disables
multiple-groups system-wide.  In most cases, however, it will be 
set to a value between \f2\s-1NGROUPS_UMIN\s+1\fP 
and \f2\s-1NGROUPS_UMAX\s+1\fP (also
defined in <\f2sys/param.h\fP>).
.PP
Only the super-user may set new groups or alter the 
value of \f2ngroups_max\fP.
.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 
.I setgroups
call will fail if:
.TP 15
.SM
\%[EPERM]
The caller is not the super-user.
.TP 15
.SM
\%[EFAULT]
The address specified for 
.I gidset
is outside the process
address space.
.TP 15
.SM
\%[EINVAL]
The
.I ngroups
parameter is greater than
.SM
.BR NGROUPS
or the kernel maximum, as specified above.
.SH "SEE ALSO
multgrps(1), getgroups(2), initgroups(3), sysconf(2)
.SH CAVEATS
The POSIX and 4.3BSD versions differ
in the types of their
.I gidset
parameter.