NAME

       getgroups - get supplementary group IDs

SYNOPSIS

       #include <unistd.h>

       int getgroups(int gidsetsize, gid_t grouplist[]);

DESCRIPTION

       The  getgroups()  function  shall fill in the array grouplist with the current supplementary group IDs of
       the calling process. It is implementation-defined whether getgroups() also returns the effective group ID
       in the grouplist array.

       The gidsetsize argument specifies the number of elements in the array grouplist.  The  actual  number  of
       group IDs stored in the array shall be returned. The values of array entries with indices greater than or
       equal to the value returned are undefined.

       If  gidsetsize  is  0,  getgroups()  shall  return the number of group IDs that it would otherwise return
       without modifying the array pointed to by grouplist.

       If the effective group ID of the process is returned with the supplementary group IDs, the value returned
       shall always be greater than or equal to one and less than or equal to the value of {NGROUPS_MAX}+1.

RETURN VALUE

       Upon successful completion, the number of supplementary group IDs shall be returned. A return value of -1
       indicates failure and errno shall be set to indicate the error.

ERRORS

       The getgroups() function shall fail if:

       EINVAL The gidsetsize argument is non-zero and less than the number of group IDs  that  would  have  been
              returned.

       The following sections are informative.

EXAMPLES

   Getting the Supplementary Group IDs of the Calling Process
       The  following  example  places the current supplementary group IDs of the calling process into the group
       array.

              #include <sys/types.h>
              #include <unistd.h>
              ...
              gid_t *group;
              int nogroups;
              long ngroups_max;

              ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1;
              group = (gid_t *)malloc(ngroups_max *sizeof(gid_t));

              ngroups = getgroups(ngroups_max, group);

APPLICATION USAGE

       None.

RATIONALE

       The related function setgroups() is a privileged operation and therefore is not covered by this volume of
       IEEE Std 1003.1-2001.

       As implied by the definition of supplementary groups, the effective group ID  may  appear  in  the  array
       returned  by  getgroups()  or  it  may  be  returned  only  by  getegid(). Duplication may exist, but the
       application needs to call getegid() to be sure of getting all of the information. Various  implementation
       variations and administrative sequences cause the set of groups appearing in the result of getgroups() to
       vary  in  order  and as to whether the effective group ID is included, even when the set of groups is the
       same (in the mathematical sense of "set"). (The history of a process and its  parents  could  affect  the
       details of the result.)

       Application writers should note that {NGROUPS_MAX} is not necessarily a constant on all implementations.

FUTURE DIRECTIONS

       None.

SEE ALSO

       getegid() , setgid() , the Base Definitions volume of IEEE Std 1003.1-2001, <sys/types.h>, <unistd.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc and The Open Group. In the event of any discrepancy between this version and the  original  IEEE  and
       The  Open  Group  Standard,  the  original  IEEE and The Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                                   2003                                          GETGROUPS(P)