.\" 2008-05-03, mtk, expanded and rewrote parts of DESCRIPTION and RETURN
.\" VALUE, made style of page more consistent with man-pages style.
.\"
-.TH GETGROUPS 2 2016-10-08 "Linux" "Linux Programmer's Manual"
+.TH GETGROUPS 2 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
getgroups, setgroups \- get/set list of supplementary group IDs
.SH SYNOPSIS
.B #include <unistd.h>
.PP
.BI "int getgroups(int " size ", gid_t " list []);
-.PP
+
.B #include <grp.h>
.PP
.BI "int setgroups(size_t " size ", const gid_t *" list );
If the calling process is a member of more than
.I size
supplementary groups, then an error results.
+.PP
It is unspecified whether the effective group ID of the calling process
is included in the returned list.
(Thus, an application should also call
.BR getegid (2)
and add or remove the resulting value.)
-
+.PP
If
.I size
is zero,
argument specifies the number of supplementary group IDs
in the buffer pointed to by
.IR list .
+A process can drop all of its supplementary groups with the call:
+.PP
+.in +4n
+.EX
+setgroups(0, NULL);
+.EE
+.in
.SH RETURN VALUE
On success,
.BR getgroups ()
On error, \-1 is returned, and
.I errno
is set appropriately.
-
+.PP
On success,
.BR setgroups ()
returns 0.
in
.BR user_namespaces (7).
.SH CONFORMING TO
+.BR getgroups ():
+SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
+.PP
+.BR setgroups ():
SVr4, 4.3BSD.
-The
-.BR getgroups ()
-function is in POSIX.1-2001 and POSIX.1-2008.
Since
.BR setgroups ()
requires privilege, it is not covered by POSIX.1.
The set of supplementary group IDs
is inherited from the parent process, and preserved across an
.BR execve (2).
-
+.PP
The maximum number of supplementary group IDs can be found at run time using
.BR sysconf (3):
-.nf
-
- long ngroups_max;
- ngroups_max = sysconf(_SC_NGROUPS_MAX);
-
-.fi
+.PP
+.in +4n
+.EX
+long ngroups_max;
+ngroups_max = sysconf(_SC_NGROUPS_MAX);
+.EE
+.in
+.PP
The maximum return value of
.BR getgroups ()
cannot be larger than one more than this value.
Since Linux 2.6.4, the maximum number of supplementary group IDs is also
exposed via the Linux-specific read-only file,
.IR /proc/sys/kernel/ngroups_max .
-
+.PP
The original Linux
.BR getgroups ()
system call supported only 16-bit group IDs.