.\" 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-03-15 "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 <sys/types.h>
.br
.B #include <unistd.h>
-.sp
+.PP
.BI "int getgroups(int " size ", gid_t " list []);
-.sp
+
.B #include <grp.h>
-.sp
+.PP
.BI "int setgroups(size_t " size ", const gid_t *" list );
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.BR setgroups ():
Since glibc 2.19:
_DEFAULT_SOURCE
Glibc 2.19 and earlier:
- _SVID_SOURCE
+ _BSD_SOURCE
.SH DESCRIPTION
.PP
.BR getgroups ()
(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.