---
name: "getgrouplist"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/getgrouplist"
---

# getgrouplist(3)

get list of groups to which a user belongs

## NAME

getgrouplist - get list of groups to which a user belongs

## LIBRARY

Standard C library (*libc*, *-lc*)

## SYNOPSIS

```
#include <grp.h>
```

**int getgrouplist(const char \****user***, gid\_t** *group***,**                  **gid\_t \****groups***, int \****ngroups***);**

Feature Test Macro Requirements for glibc (see [**feature\_test\_macros**(7)](/feature_test_macros/7.md)):

**getgrouplist**():

```
    Since glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.19 and earlier:
        _BSD_SOURCE
```

## DESCRIPTION

The **getgrouplist**() function scans the group database (see [**group**(5)](/group/5.md)) to obtain the list of groups that *user* belongs to. Up to *\*ngroups* of these groups are returned in the array *groups*.

If it was not among the groups defined for *user* in the group database, then *group* is included in the list of groups returned by **getgrouplist**(); typically this argument is specified as the group ID from the password record for *user*.

The *ngroups* argument is a value-result argument: on return it always contains the number of groups found for *user*, including *group*; this value may be greater than the number of groups stored in *groups*.

## RETURN VALUE

If the number of groups of which *user* is a member is less than or equal to *\*ngroups*, then the value *\*ngroups* is returned.

If the user is a member of more than *\*ngroups* groups, then **getgrouplist**() returns -1. In this case, the value returned in *\*ngroups* can be used to resize the buffer passed to a further call to **getgrouplist**().

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **getgrouplist**() | Thread safety | MT-Safe locale |

## STANDARDS

None.

## HISTORY

glibc 2.2.4.

## BUGS

Before glibc 2.3.3, the implementation of this function contains a buffer-overrun bug: it returns the complete list of groups for *user* in the array *groups*, even when the number of groups exceeds *\*ngroups*.

## EXAMPLES

The program below displays the group list for the user named in its first command-line argument. The second command-line argument specifies the *ngroups* value to be supplied to **getgrouplist**(). The following shell session shows examples of the use of this program:

```
$ ./a.out cecilia 0
getgrouplist() returned -1
ngroups = 3
$ ./a.out cecilia 3
ngroups = 3
16 (dialout)
33 (video)
100 (users)
```

### Program source

```
#include <errno.h>
#include <grp.h>
#include <pwd.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
    int            ngroups;
    gid_t          *groups;
    struct group   *gr;
    struct passwd  *pw;
    if (argc != 3) {
        fprintf(stderr, "Usage: %s <user> <ngroups>\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    ngroups = atoi(argv[2]);
    groups = malloc(sizeof(*groups) * ngroups);
    if (groups == NULL) {
        perror("malloc");
        exit(EXIT_FAILURE);
    }
    /* Fetch passwd structure (contains first group ID for user).  */
    errno = 0;
    pw = getpwnam(argv[1]);
    if (pw == NULL) {
        if (errno)
            perror("getpwnam");
        else
            fprintf(stderr, "no such user\n");
        exit(EXIT_FAILURE);
    }
    /* Retrieve group list.  */
    if (getgrouplist(argv[1], pw->pw_gid, groups, &ngroups) == -1) {
        fprintf(stderr, "getgrouplist() returned -1\n");
        fprintf(stderr, "ngroups = %d\n", ngroups);
        exit(EXIT_FAILURE);
    }
    /* Display list of retrieved groups, along with group names.  */
    fprintf(stderr, "ngroups = %d\n", ngroups);
    for (int j = 0; j < ngroups; j++) {
        printf("%d", groups[j]);
        gr = getgrgid(groups[j]);
        if (gr != NULL)
            printf(" (%s)", gr->gr_name);
        printf("\n");
    }
    exit(EXIT_SUCCESS);
}
```

## SEE ALSO

[**getgroups**(2)](/getgroups/2.md), [**setgroups**(2)](/setgroups/2.md), [**getgrent**(3)](/getgrent/3.md), [**group\_member**(3)](/group_member/3.md), [**group**(5)](/group/5.md), [**passwd**(5)](/passwd/5.md)