GETGROUPLIST(3C) Standard C Library Functions GETGROUPLIST(3C)

NAME

getgrouplist - calculate group access list

SYNOPSIS

#include <grp.h>

int
getgrouplist(const char *user, gid_t agroup, gid_t *groups, int *ngroups);

DESCRIPTION

The getgrouplist() function queries the group database to obtain the list
of groups that user belongs to. The agroup group is always added to the
resulting group list. This value is typically the primary gid of the user
from the passwd database.

When calling getgrouplist(), the caller should set the maximum number of
groups that groups can hold in *ngroups. The value of NGROUPS_MAX can be
used to size groups to ensure it can hold any number of groups supported by
the system.

Upon return, getgrouplist() stores the list of groups that user belongs to
in groups and stores the number of groups user belongs to in *ngroups (this
may be a smaller than the value passed in when calling getgrouplist()). If
groups is too small to hold all of the groups user belongs to,
getgrouplist() fails and sets *ngroups to a value large enough to hold the
full result.

RETURN VALUES

On success, getgrouplist() returns the number of groups user belongs to,
fills in groups with the gids of the groups user belongs to, and also sets
*ngroups to the number of groups user belongs to.

On failure, getgrouplist() returns -1 and errno is set.

The behavior of getgrouplist() is undefined if the total number of groups a
user belongs to exceeds NGROUPS_MAX.

Note that on FreeBSD, getgrouplist() always returns -1 on failure or 0 on
success. A caller must rely on the value set in *ngroups upon return to
determine the number of entries in groups.

On Linux, both glibc and musl return the number of groups user belongs to
on success and return -1 on failure.

None of these other implementations document any errno values on failure,
however their implementations show that errno may be set on failure.
Software using getgrouplist() should be aware of these differences when
attempting to write portable software.

EXAMPLES

Example 1 Print all the groups for a user.

#include <pwd.h>
#include <grp.h>
#include <stdlib.h>
#include <stdio.h>
#include <limits.h>
#include <err.h>

void
printgroups(const char *user)
{
struct passwd *pw;
gid_t *groups;
int ngroups, ret;

if ((groups = calloc(NGROUPS_MAX, sizeof (gid_t))) == NULL)
err(EXIT_FAILURE, "calloc");

if ((pw = getpwnam(user)) == NULL)
err(EXIT_FAILURE, "getpwnam");

ngroups = NGROUPS_MAX;
ret = getgrouplist(user, pw->pw_gid, groups, &ngroups);
if (ret < 0)
err(EXIT_FAILURE, "getgrouplist");

for (int i = 0; i < ret; i++) {
struct group *gr = getgrgid(groups[i]);

(void) printf("%s ", gr->gr_name);
}
(void) fputc('\n', stdout);

free(groups);
}

ERRORS

On failure, getgrouplist() returns -1, and will set errno to one of the
following values:

ENOMEM Not enough memory to complete the request.

EINVAL One of the parameters is invalid (for example, ngroups is
NULL).

ERANGE The supplied value of *ngroups is too small to hold the
results. *ngroups is set (upon return) to a value large
enough to hold the results, and a partial set of results is
written to groups. The value written to *ngroups may be
larger than the value returned by a successful call to
getgrouplist().

INTERFACE STABILITY

Uncommitted

MT-LEVEL
MT-Safe

SEE ALSO

groups(1), getgroups(2), getuid(2), getgrnam(3C), initgroups(3C),
limits.h(3HEAD)

OmniOS January 17, 2022 OmniOS