1 files changed, 219 insertions, 0 deletions
diff --git a/man/man2/getgroups.2 b/man/man2/getgroups.2
new file mode 100644
index 000000000..3d9be4b98
--- /dev/null
+++ b/man/man2/getgroups.2
@@ -0,0 +1,219 @@
+.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
+.\" and Copyright (C) 2008, 2010, 2015, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"     Added notes on capability requirements
+.\" 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 (date) "Linux man-pages (unreleased)"
+.SH NAME
+getgroups, setgroups \- get/set list of supplementary group IDs
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "int getgroups(int " size ", gid_t " list []);
+.P
+.B #include <grp.h>
+.P
+.BI "int setgroups(size_t " size ", const gid_t *_Nullable " list );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR setgroups ():
+.nf
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    glibc 2.19 and earlier:
+        _BSD_SOURCE
+.fi
+.SH DESCRIPTION
+.BR getgroups ()
+returns the supplementary group IDs of the calling process in
+.IR list .
+The argument
+.I size
+should be set to the maximum number of items that can be stored in the
+buffer pointed to by
+.IR list .
+If the calling process is a member of more than
+.I size
+supplementary groups, then an error results.
+.P
+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.)
+.P
+If
+.I size
+is zero,
+.I list
+is not modified, but the total number of supplementary group IDs for the
+process is returned.
+This allows the caller to determine the size of a dynamically allocated
+.I list
+to be used in a further call to
+.BR getgroups ().
+.P
+.BR setgroups ()
+sets the supplementary group IDs for the calling process.
+Appropriate privileges are required (see the description of the
+.B EPERM
+error, below).
+The
+.I size
+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:
+.P
+.in +4n
+.EX
+setgroups(0, NULL);
+.EE
+.in
+.SH RETURN VALUE
+On success,
+.BR getgroups ()
+returns the number of supplementary group IDs.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.P
+On success,
+.BR setgroups ()
+returns 0.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+.I list
+has an invalid address.
+.P
+.BR getgroups ()
+can additionally fail with the following error:
+.TP
+.B EINVAL
+.I size
+is less than the number of supplementary group IDs, but is not zero.
+.P
+.BR setgroups ()
+can additionally fail with the following errors:
+.TP
+.B EINVAL
+.I size
+is greater than
+.B NGROUPS_MAX
+(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
+.TP
+.B ENOMEM
+Out of memory.
+.TP
+.B EPERM
+The calling process has insufficient privilege
+(the caller does not have the
+.B CAP_SETGID
+capability in the user namespace in which it resides).
+.TP
+.BR EPERM " (since Linux 3.19)"
+The use of
+.BR setgroups ()
+is denied in this user namespace.
+See the description of
+.IR /proc/ pid /setgroups
+in
+.BR user_namespaces (7).
+.SH VERSIONS
+.SS C library/kernel differences
+At the kernel level, user IDs and group IDs are a per-thread attribute.
+However, POSIX requires that all threads in a process
+share the same credentials.
+The NPTL threading implementation handles the POSIX requirements by
+providing wrapper functions for
+the various system calls that change process UIDs and GIDs.
+These wrapper functions (including the one for
+.BR setgroups ())
+employ a signal-based technique to ensure
+that when one thread changes credentials,
+all of the other threads in the process also change their credentials.
+For details, see
+.BR nptl (7).
+.SH STANDARDS
+.TP
+.BR getgroups ()
+POSIX.1-2008.
+.TP
+.BR setgroups ()
+None.
+.SH HISTORY
+.TP
+.BR getgroups ()
+SVr4, 4.3BSD, POSIX.1-2001.
+.TP
+.BR setgroups ()
+SVr4, 4.3BSD.
+Since
+.BR setgroups ()
+requires privilege, it is not covered by POSIX.1.
+.P
+The original Linux
+.BR getgroups ()
+system call supported only 16-bit group IDs.
+Subsequently, Linux 2.4 added
+.BR getgroups32 (),
+supporting 32-bit IDs.
+The glibc
+.BR getgroups ()
+wrapper function transparently deals with the variation across kernel versions.
+.SH NOTES
+A process can have up to
+.B NGROUPS_MAX
+supplementary group IDs
+in addition to the effective group ID.
+The constant
+.B NGROUPS_MAX
+is defined in
+.IR <limits.h> .
+The set of supplementary group IDs
+is inherited from the parent process, and preserved across an
+.BR execve (2).
+.P
+The maximum number of supplementary group IDs can be found at run time using
+.BR sysconf (3):
+.P
+.in +4n
+.EX
+long ngroups_max;
+ngroups_max = sysconf(_SC_NGROUPS_MAX);
+.EE
+.in
+.P
+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 .
+.SH SEE ALSO
+.BR getgid (2),
+.BR setgid (2),
+.BR getgrouplist (3),
+.BR group_member (3),
+.BR initgroups (3),
+.BR capabilities (7),
+.BR credentials (7)