getgrouplist()

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.

Note: This function is in libc.a, but not in libc.so (in order to save space).

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().