| .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) |
| .\" and Copyright (C) 2008, 2010, 2015, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| getgroups, setgroups \- get/set list of supplementary group IDs |
| .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 *" 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 |
| .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 () |
| 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 |
| .BR 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 CONFORMING TO |
| .BR getgroups (): |
| SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. |
| .PP |
| .BR setgroups (): |
| SVr4, 4.3BSD. |
| Since |
| .BR setgroups () |
| requires privilege, it is not covered by POSIX.1. |
| .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 . |
| .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. |
| .\" |
| .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 SEE ALSO |
| .BR getgid (2), |
| .BR setgid (2), |
| .BR getgrouplist (3), |
| .BR group_member (3), |
| .BR initgroups (3), |
| .BR capabilities (7), |
| .BR credentials (7) |