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.
The Neutrino implementation of getgrouplist() ignores the basegid argument; see the Caveats, below.
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.

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.

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_MAX];

   ngroups = NGROUPS_MAX;
   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().
  • This routine is BSD, and was designed for a system in which the effective group ID is placed in the supplementary group list. Neutrino doesn't do this, so it ignores the basegid argument.