Movatterモバイル変換

getgroups(2) — Linux manual page

NAME \|LIBRARY \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|VERSIONS \|STANDARDS \|HISTORY \|NOTES \|EXAMPLES \|SEE ALSO \|COLOPHON

getgroups(2)               System Calls Manualgetgroups(2)

NAME top

       getgroups, setgroups - get/set list of supplementary group IDs

LIBRARY top

       Standard C library (libc,-lc)

SYNOPSIS top

#include <unistd.h>int getgroups(intsize, gid_tlist[_Nullablesize]);#include <grp.h>int setgroups(size_tsize, const gid_tlist[_Nullablesize]);   Feature Test Macro Requirements for glibc (seefeature_test_macros(7)):setgroups():           Since glibc 2.19:               _DEFAULT_SOURCE           glibc 2.19 and earlier:               _BSD_SOURCE

DESCRIPTION top

getgroups() returns the supplementary group IDs of the calling       process inlist.  The argumentsize should be set to the maximum       number of items that can be stored in the buffer pointed to bylist.  If the calling process is a member of more thansize       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 callgetegid(2) and add or remove the resulting       value.)       Ifsize 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 allocatedlist       to be used in a further call togetgroups().setgroups() sets the supplementary group IDs for the calling       process.  Appropriate privileges are required (see the description       of theEPERMerror, below).  Thesize argument specifies the       number of supplementary group IDs in the buffer pointed to bylist.  A process can drop all of its supplementary groups with the       call:           setgroups(0, NULL);

RETURN VALUE top

       On success,getgroups() returns the number of supplementary group       IDs.  On error, -1 is returned, anderrno is set to indicate the       error.       On success,setgroups() returns 0.  On error, -1 is returned, anderrno is set to indicate the error.

ERRORS top

EFAULTlist has an invalid address.getgroups() can additionally fail with the following error:EINVALsize is less than the number of supplementary group IDs,              but is not zero.setgroups() can additionally fail with the following errors:EINVALsize is greater thanNGROUPS_MAX(32 before Linux 2.6.4;              65536 since Linux 2.6.4).ENOMEMOut of memory.EPERMThe calling process has insufficient privilege (the caller              does not have theCAP_SETGIDcapability in the user              namespace in which it resides).EPERM(since Linux 3.19)              The use ofsetgroups() is denied in this user namespace.              See the description of/proc/pid/setgroups inuser_namespaces(7).

VERSIONS top

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 forsetgroups()) 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, seenptl(7).

STANDARDS top

getgroups()              POSIX.1-2008.setgroups()              None.

HISTORY top

getgroups()              SVr4, 4.3BSD, POSIX.1-2001.setgroups()              SVr4, 4.3BSD.  Sincesetgroups() requires privilege, it is              not covered by POSIX.1.       The original Linuxgetgroups() system call supported only 16-bit       group IDs.  Subsequently, Linux 2.4 addedgetgroups32(),       supporting 32-bit IDs.  The glibcgetgroups() wrapper function       transparently deals with the variation across kernel versions.

NOTES top

       A process can have up toNGROUPS_MAXsupplementary group IDs in       addition to the effective group ID.  The constantNGROUPS_MAXis       defined in<limits.h>.  The set of supplementary group IDs is       inherited from the parent process, and preserved across anexecve(2).       The maximum number of supplementary group IDs can be found at run       time usingsysconf(3):           long ngroups_max;           ngroups_max = sysconf(_SC_NGROUPS_MAX);       The maximum return value ofgetgroups() 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,/proc/sys/kernel/ngroups_max.

EXAMPLES top

       #include <err.h>       #include <stddef.h>       #include <stdint.h>       #include <stdio.h>       #include <stdlib.h>       #include <sys/types.h>       #include <unistd.h>       #define MALLOC(n, T)  ((T *) reallocarray(NULL, n, sizeof(T)))       static gid_t *agetgroups(size_t *ngids);       int       main(void)       {           gid_t   *gids;           size_t  n;           gids = agetgroups(&n);           if (gids == NULL)               err(EXIT_FAILURE, "agetgroups");           if (n != 0) {               printf("%jd", (intmax_t) gids[0]);               for (size_t i = 1; i < n; i++)                   printf(" %jd", (intmax_t) gids[i]);           }           puts("");           free(gids);           exit(EXIT_SUCCESS);       }       static gid_t *       agetgroups(size_t *ngids)       {           int    n;           gid_t  *gids;           n = getgroups(0, NULL);           if (n == -1)               return NULL;           gids = MALLOC(n, gid_t);           if (gids == NULL)               return NULL;           n = getgroups(n, gids);           if (n == -1) {               free(gids);               return NULL;           }           *ngids = n;           return gids;       }

COLOPHON top

       This page is part of theman-pages (Linux kernel and C library       user-space interface documentation) project.  Information about       the project can be found at        ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report       for this manual page, see       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.       This page was obtained from the tarball man-pages-6.15.tar.gz       fetched from       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on       2025-08-11.  If you discover any rendering problems in this HTML       version of the page, or you believe there is a better or more up-       to-date source for the page, or you have corrections or       improvements to the information in this COLOPHON (which isnot       part of the original manual page), send a mail to       man-pages@man7.orgLinux man-pages 6.15            2025-05-17getgroups(2)

Pages that refer to this page:capsh(1), groups(1@@shadow-utils), ps(1), unshare(1), syscalls(2), cap_get_proc(3), getgrouplist(3), group_member(3), id_t(3type), initgroups(3), credentials(7), nptl(7), path_resolution(7), signal-safety(7), user_namespaces(7)