user_namespaces.7: Minor rewordings of recently added text

[thirdparty/man-pages.git] / man2 / getgroups.2

diff --git a/man2/getgroups.2 b/man2/getgroups.2
index 71d2a3b2e90b988e5ad76594fbbd7c840fe51e33..ebe0d60cd1dcdaedbf5caa8dacb1afead8a55577 100644 (file)
--- a/man2/getgroups.2
+++ b/man2/getgroups.2
@@ -29,27 +29,30 @@
 .\" 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 2015-03-29 "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 ():
-_BSD_SOURCE
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    Glibc 2.19 and earlier:
+        _BSD_SOURCE
 .SH DESCRIPTION
 .PP
 .BR getgroups ()
@@ -68,7 +71,7 @@ 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,
@@ -82,14 +85,21 @@ to be used in a further call to
 .PP
 .BR setgroups ()
 sets the supplementary group IDs for the calling process.
-Appropriate privileges (Linux: the
-.B CAP_SETGID
-capability) are required.
+Appropriate privileges are required (see the description of the
+.BR 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:
+.PP
+.in +4n
+.EX
+setgroups(0, NULL);
+.EE
+.in
 .SH RETURN VALUE
 On success,
 .BR getgroups ()
@@ -97,7 +107,7 @@ returns the number of supplementary group IDs.
 On error, \-1 is returned, and
 .I errno
 is set appropriately.
-
+.PP
 On success,
 .BR setgroups ()
 returns 0.
@@ -131,9 +141,9 @@ Out of memory.
 .TP
 .B EPERM
 The calling process has insufficient privilege
-(it does not have the
+(the caller does not have the
 .BR CAP_SETGID
-capability).
+capability in the user namespace in which it resides).
 .TP
 .BR EPERM " (since Linux 3.19)"
 The use of
@@ -144,13 +154,14 @@ See the description of
 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.
 Since
 .BR setgroups ()
-requires privilege, it is not covered by POSIX.1-2001.
+requires privilege, it is not covered by POSIX.1.
 .SH NOTES
 A process can have up to
 .B NGROUPS_MAX
@@ -163,22 +174,24 @@ is defined in
 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.
@@ -189,7 +202,7 @@ The glibc
 .BR getgroups ()
 wrapper function transparently deals with the variation across kernel versions.
 .\"
-.SS C library/kernel ABI differences
+.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.