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);


DESCRIPTION

       getgroups
              Up to size supplementary group IDs 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.
              Only the super-user may use this function.


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.

       EPERM  For setgroups, the user is not the super-user.

       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.


NOTES

       A process can have up to at least  NGROUPS_MAX  supplemen­
       tary  group IDs in addition to the effective group ID. The
       set of supplementary group IDs is inherited from the  par­
       ent  process  and  may  be  changed  using setgroups.  The

       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.

       The  prototype  for  setgroups  is   only   available   if
       _BSD_SOURCE  is defined (either explicitly, or implicitly,
       by not defining _POSIX_SOURCE or compiling with the  -ansi
       flag).


CONFORMING TO

       SVr4,  SVID (issue 4 only; these calls were not present in
       SVr3), X/OPEN,  4.3BSD.   The  getgroups  function  is  in
       POSIX.1.   Since  setgroups  requires privilege, it is not
       covered by POSIX.1.


SEE ALSO

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


Man(1) output converted with man2html