getgrouplist()

Updated: April 19, 2023

Determine the group access list for a user

Synopsis:

#include <unistd.h>

int getgrouplist( const char *name,
                  gid_t basegid,
                  gid_t *groups,
                  int *ngroups );

Arguments:

name
The name of the user.
basegid
The basegid is automatically included in the list of groups. Typically this value is given as the group number from the password file.
groups
A pointer to an array where the function can store the group IDs.
ngroups
A pointer to the size of the groups array. The function sets the value pointed to by ngroups to be the actual number of groups found.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The getgrouplist() function reads the group file and determines the group access list for the user specified in name, automatically adding basegid.

Returns:

0
Success; the function fills in the group array and sets *ngroups to the number of groups found.
-1
The groups array is too small to hold all the user's groups. The function fills the group array with as many groups as fit.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <unistd.h>
#include <limits.h>

int main()
{
   int ngroups, i;
   gid_t *groups;

   ngroups = sysconf( _SC_NGROUPS_MAX );
   groups = (gid_t *) malloc ( ngroups * sizeof (gid_t) );
   if (groups == NULL) {
      perror ("malloc()");
      return EXIT_FAILURE;
   }

   if ( getgrouplist( getlogin(), getegid(), groups, &ngroups) == -1) {
           printf ("Groups array is too small: %d\n", ngroups);
   }

   printf ("%s belongs to these groups: %d", getlogin(), getegid());
   for (i=0; i < ngroups; i++) {
           printf (", %d", groups[i]);
   }
   printf ("\n");

   return EXIT_SUCCESS;
}

Files:

/etc/group
Group membership list.

Classification:

Unix

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:

The getgrouplist() function uses the routines based on getgrent(). If the invoking program uses any of these routines, the group structure will be overwritten in the call to getgrouplist().