GETGROUPS(2)        Linux Programmer's Manual        GETGROUPS(2)



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


       #define _BSD_SOURCE
       #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.


NOTE

       A process can have up to at least  NGROUPS_MAX  supplemen-
       tary  group IDs in addition to the effective group ID. The



Linux 2.0.32             10 December 1997                       1





GETGROUPS(2)        Linux Programmer's Manual        GETGROUPS(2)


       set of supplementary group IDs is inherited from the  par-
       ent process and may be changed using setgroups.  The maxi-
       mum 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.


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.


BUGS

       The  _BSD_SOURCE  flag  probably shouldn't be required for
       setgroups.


SEE ALSO

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




































Linux 2.0.32             10 December 1997                       2