getgroups() — Get a list of supplementary group IDs

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <unistd.h>

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

General description

Stores the supplementary group IDs of the calling process in the list array. size gives the number of gid_t elements that can be stored in the list array.

Returned value

If successful, getgroups() returns the number of supplementary group IDs that it puts into list. This value is always greater than or equal to 1 and less than or equal to the value of NGROUPS_MAX (which is defined in the limits.h header file).

If size is zero, getgroups() returns the total number of supplementary group IDs for the process. getgroups() does not try to store group IDs in list.

If unsuccessful, getgroups() returns -1 and sets errno to one of the following values.

Error Code: Description
EINVAL: size was not equal to 0 and is less than the total number of supplementary group IDs for the process. list may or may not contain a subset of the supplementary group IDs for the process.

Example

CELEBG10

⁄* CELEBG10

   This example provides a list of the supplementary group IDs.

 *⁄
#define _POSIX_SOURCE
#include <sys⁄types.h>
#include <grp.h>
#include <stdio.h>
#include <unistd.h>

#define dim(x) (sizeof(x)⁄sizeof(x[0]))

main() {
  gid_t gids[500];
  struct group *grp;
  int count, curr;

  if ((count = getgroups(dim(gids), gids)) == -1)
    perror("getgroups() error");
  else {
    puts("The following is the list of my supplementary groups:");
    for (curr=0; curr<count; curr++) {
      if ((grp = getgrgid(gids[curr])) == NULL)
        perror("getgrgid() error");
      else
        printf("  %8s (%d)\n", grp->gr_name, (int) gids[curr]);
    }
  }
}

Output

The following is the list of my supplementary groups:
      SYS1 (500)
     KINGS (512)
    NOBLES (513)
   KNIGHTS (514)
   WIZARDS (515)
   SCRIBES (516)
   JESTERS (517)
  PEASANTS (518)