This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

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

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.

See also:

initgroups(), setgroups()