Section (2) getgroups
getgroups, setgroups — get/set list of supplementary group IDs
#include <sys/types.h> #include <unistd.h>
|const gid_t *list
getgroups() returns the
supplementary group IDs of the calling process in
list. The argument
size should be set to the
maximum number of items that can be stored in the buffer
pointed to by
If the calling process is a member of more than
size supplementary groups, then
an error results.
It is unspecified whether the effective group ID of the calling process is included in the returned list. (Thus, an application should also call getegid(2) and add or remove the resulting value.)
size is zero,
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
list to be used in a further
setgroups() sets the
supplementary group IDs for the calling process. Appropriate
privileges are required (see the description of the
EPERM error, below). The
specifies the number of supplementary group IDs in the buffer
pointed to by
process can drop all of its supplementary groups with the
returns the number of supplementary group IDs. On error,
−1 is returned, and
is set appropriately.
returns 0. On error, −1 is returned, and
errno is set appropriately.
listhas an invalid address.
getgroups() can additionally
fail with the following error:
sizeis less than the number of supplementary group IDs, but is not zero.
setgroups() can additionally
fail with the following errors:
sizeis greater than
NGROUPS_MAX(32 before Linux 2.6.4; 65536 since Linux 2.6.4).
Out of memory.
The calling process has insufficient privilege (the caller does not have the
CAP_SETGIDcapability in the user namespace in which it resides).
- EPERM (since Linux 3.19)
The use of
setgroups() is denied in this user namespace. See the description of
getgroups(): SVr4, 4.3BSD,
setgroups(): SVr4, 4.3BSD.
privilege, it is not covered by POSIX.1.
A process can have up to
NGROUPS_MAX supplementary group IDs in
addition to the effective group ID. The constant
NGROUPS_MAX is defined in
The set of supplementary group IDs is inherited from the
parent process, and preserved across an execve(2).
The maximum number of supplementary group IDs can be found at run time using sysconf(3):
long ngroups_max; ngroups_max = sysconf(_SC_NGROUPS_MAX);
The maximum return value of
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,
The original Linux
getgroups() system call supported only
16-bit group IDs. Subsequently, Linux 2.4 added
getgroups32(), supporting 32-bit IDs. The
function transparently deals with the variation across kernel
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
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 nptl(7).
This page is part of release 5.04 of the Linux
man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
Copyright 1993 Rickard E. Faith (faithcs.unc.edu)
and Copyright (C) 2008, 2010, 2015, Michael Kerrisk <mtk.manpagesgmail.com>
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
Formatted or processed versions of this manual, if unaccompanied by
the source, must acknowledge the copyright and authors of this work.
Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond <esrthyrsus.com>
Modified, 27 May 2004, Michael Kerrisk <mtk.manpagesgmail.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.