diff options
Diffstat (limited to 'man2/getgroups.2')
| -rw-r--r-- | man2/getgroups.2 | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/man2/getgroups.2 b/man2/getgroups.2 new file mode 100644 index 0000000..eb282b9 --- /dev/null +++ b/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 2023-03-30 "Linux man-pages 6.05.01" +.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> +.PP +.BI "int getgroups(int " size ", gid_t " list []); +.PP +.B #include <grp.h> +.PP +.BI "int setgroups(size_t " size ", const gid_t *_Nullable " list ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.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. +.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, +.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 (). +.PP +.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: +.PP +.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. +.PP +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. +.PP +.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. +.PP +.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. +.PP +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). +.PP +The maximum number of supplementary group IDs can be found at run time using +.BR sysconf (3): +.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 . +.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) |