setgroups − get/set list of supplementary group
getgroups(int size, gid_t
setgroups(size_t size, const gid_t
Macro Requirements for glibc (see
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 list. 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
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 call to
sets the supplementary group IDs for the calling process.
Appropriate privileges (Linux: the CAP_SETGID
capability) are required. The size argument specifies
the number of supplementary group IDs in the buffer pointed
to by list.
getgroups() returns the number of supplementary group
IDs. On error, −1 is returned, and errno is set
setgroups() returns 0. On error, −1 is
returned, and errno is set appropriately.
list has an invalid
can additionally fail with the following error:
size is less than the
number of supplementary group IDs, but is not zero.
can additionally fail with the following errors:
size is greater than
NGROUPS_MAX (32 before Linux 2.6.4; 65536 since Linux
Out of memory.
The calling process has insufficient privilege (it does
not have the CAP_SETGID capability).
EPERM (since Linux
The use of setgroups()
is denied in this user namespace. See the description of
The getgroups() function is in POSIX.1-2001 and
POSIX.1-2008. Since setgroups() requires 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 <limits.h>.
The set of supplementary group IDs is inherited from the
parent process, and preserved across an
number of supplementary group IDs can be found at run time
ngroups_max = sysconf(_SC_NGROUPS_MAX);
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,
Linux getgroups() system call supported only 16-bit
group IDs. Subsequently, Linux 2.4 added
getgroups32(), supporting 32-bit IDs. The glibc
getgroups() wrapper function transparently deals with
the variation across kernel versions.
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
This page is
part of release 4.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