getgroupsbyname() — Get supplementary group IDs by user name

Standards

Standards / Extensions	C or C++	Dependencies
z/OS® UNIX	both

Format

#define _POSIX_SOURCE
#include <unistd.h>

int getgroupsbyname(char username[], int size, gid_t list[]);

General description

Stores the supplementary group IDs of the specified username in the array, list. size gives the number of gid_t elements that can be stored in the array, list.

Returned value

If successful, getgroupsbyname() returns the number of supplementary group IDs that it puts into list. This value is always greater than or equal to one, and less than or equal to the value of NGROUPS_MAX.

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

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

Error Code: Description
EINVAL: size was less than or equal to 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

CELEBG11

⁄* CELEBG11

   This example provides a list of the supplementary group IDs for
   MVSUSR1.

 *⁄
#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;
  char user[]="MVSUSR1";

  if ((count = getgroupsbyname(user, dim(gids), gids)) == -1)
    perror("getgroups() error");
  else {
    printf("The following is the list of %s's supplementary groups:\n",
           user);
    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 MVSUSR1's supplementary groups:
      SYS1 (500)
     USERS (523)