Ubuntu manuals

Provided by: manpages-dev_2.77-1_all

NAME

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

SYNOPSIS

       #include <sys/types.h>
       #include <unistd.h>

       int getgroups(int size, gid_t list[]);

       #include <grp.h>

       int setgroups(size_t size, const gid_t *list);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       setgroups(): _BSD_SOURCE

DESCRIPTION

       getgroups()
              Up  to size supplementary group IDs (of the calling process) are
              returned in list.  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.)   If  size  is zero, list is not
              modified, but the total number of supplementary  group  IDs  for
              the process is returned.

       setgroups()
              Sets  the  supplementary group IDs for the process.  Appropriate
              privileges (Linux: the CAP_SETGID capability) are required.

RETURN VALUE

       getgroups()
              On success, the number of supplementary group IDs  is  returned.
              On error, -1 is returned, and errno is set appropriately.

       setgroups()
              On  success,  zero  is  returned.  On error, -1 is returned, and
              errno is set appropriately.

ERRORS

       EFAULT list has an invalid address.

       EINVAL For setgroups(), size is greater  than  NGROUPS  (32  for  Linux
              2.0.32).   For  getgroups(),  size  is  less  than the number of
              supplementary group IDs, but is not zero.

       EPERM  The  calling  process  has  insufficient   privilege   to   call
              setgroups().

CONFORMING TO

       SVr4,  4.3BSD.   The  getgroups()  function  is in POSIX.1-2001.  Since
       setgroups() requires privilege, it is not covered by POSIX.1-2001.

NOTES

       A process can have up to at least NGROUPS_MAX supplementary  group  IDs
       in  addition to the effective group ID.  The set of supplementary group
       IDs is inherited from the parent  process  and  may  be  changed  using
       setgroups().   The  maximum  number  of  supplementary group IDs can be
       found using sysconf(3):

           long ngroups_max;
           ngroups_max = sysconf(_SC_NGROUPS_MAX);

       The maximal return value of getgroups() cannot be larger than one  more
       than the value obtained this way.

SEE ALSO

       getgid(2), setgid(2), initgroups(3), capabilities(7)

COLOPHON

       This  page  is  part of release 2.77 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://www.kernel.org/doc/man-pages/.