getgroups()--Get Group IDs


  Syntax
 #include <unistd.h>

 int getgroups(int gidsetsize, gid_t grouplist[])
  Service Program Name: QSYPAPI

  Default Public Authority: *USE

  Threadsafe: No

If the gidsetsize argument is zero, getgroups() returns the number of group IDs associated with the calling thread without modifying the array pointed to by the grouplist argument. The number of group IDs includes the effective group ID and the supplementary group IDs. Otherwise, getgroups() fills in the array grouplist with the effective group ID and supplementary group IDs of the calling thread and returns the actual number of group IDs stored. The values of array entries with indexes larger than or equal to the returned value are undefined.


Parameters

gidsetsize
(Input) The number of elements in the supplied array grouplist.

grouplist
(Output) The effective group ID and supplementary group IDs. The first element in grouplist is the effective group ID.

Authorities

No authorization is required.


Return Value

0 or > 0 getgroups() was successful. If the gidsetsize argument is 0, the number of group IDs is returned. This number includes the effective group ID and supplementary group IDs. If gidsetsize is greater than 0, the array grouplist is filled with the effective group ID and supplementary group IDs of the calling thread and the return value represents the actual number of group IDs stored.
-1 getgroups() was not successful. The errno global variable is set to indicate the error.


Error Conditions

If getgroups() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Error condition Additional information
[EINVAL]

The gidsetsize argument is not equal to zero and is less than the number of group IDs.

Usage Notes

This function can be used in two different ways. First, if called with gidsetsize equal to 0, it is used to return the number of groups associated with a thread. Second, if called with gidsetsize not equal to 0, it is used to return a list of the GIDs representing the effective and supplementary groups associated with a thread. In this case, the gidsetsize argument represents how much space is available in the grouplist argument.

The calling routine can choose to call this function with gidsetsize equal to 0 to determine how much space to allocate for a second call to this function. The second call returns the values. The following is an example of this method:

int numgroups;
gid_t *grouplist;

numgroups = getgroups(0,NULL);
grouplist = (gid_t *) calloc( numgroups, sizeof(gid_t) );
if (getgroups( numgroups, grouplist) != -1) {
        .
        .
}

Alternatively, the calling routine can choose to create enough space for NGROUPS_MAX entries to ensure enough space is available for the maximum possible number of entries that may be returned. This introduces the possibility of wasted space. The following is an example of this method:

int numgroups;
gid_t grouplist[ NGROUPS_MAX ];

if ( getgroups( NGROUPS_MAX, grouplist ) != -1 ) {
        .
        .
}

Related Information


API introduced: V3R1
Top | UNIX-Type APIs | APIs by category