---
name: "getgroups"
section: "2"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/getgroups"
---

# getgroups(2)

get the calling process' supplementary groups

## NAME

**getgroups** – get the calling process' supplementary groups

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<unistd.h\>**

*int*\

**getgroups**(*int gidsetlen*, *gid\_t \*gidset*);

## DESCRIPTION

The **getgroups**() system call gets the calling process' supplementary groups and stores them in the *gidset* array in strictly ascending order. The value of *gidsetlen* indicates the maximum number of entries that may be placed in *gidset*.

If *gidsetlen* is zero, **getgroups**() returns the cardinal of the calling process' supplementary groups set and ignores argument *gidset*.

No more than {NGROUPS\_MAX} values may ever be returned. The value of {NGROUPS\_MAX} should be obtained using [sysconf(3)](/sysconf/3.md) to avoid hard-coding it into the executable.

## RETURN VALUES

On success, the **getgroups**() system call returns the cardinal of the supplementary groups set. It always succeeds if argument *gidsetlen* is zero.

A value of -1 indicates that an error occurred, and the error code is stored in the global variable *errno*.

## ERRORS

The possible errors for **getgroups**() are:

- \[EINVAL\]

  The argument *gidsetlen* is smaller than the number of supplementary groups (but not zero).

- \[EFAULT\]

  An invalid address was encountered while reading from the *gidset* array.

## SEE ALSO

[setgroups(2)](/setgroups/2.md), [initgroups(3)](/initgroups/3.md), [sysconf(3)](/sysconf/3.md)

## STANDARDS

The **getgroups**() system call conforms to IEEE Std 1003.1-2008 (“POSIX.1”), not reporting the effective group ID.

## HISTORY

The **getgroups**() system call appeared in 4.2BSD.

Since FreeBSD 14.3, the **getgroups**() system call has been reporting the supplementary groups in strictly ascending order.

Before FreeBSD 15.0, the **getgroups**() system call would additionally return the effective group ID as the first element of the array, before the supplementary groups.

## SECURITY CONSIDERATIONS

The **getgroups**() system call gets the supplementary groups set in the *gidset* array. In particular, as evoked in HISTORY, it does not anymore retrieve the effective group ID in the first slot of *gidset*. Programs that process this slot in a specific way must be modified to obtain the effective group ID through other means, such as a call to [getegid(2)](/getegid/2.md).

The effective group ID is present in the supplementary groups set if and only if it was explicitly set as a supplementary group. The function **initgroups**() enforces that, while the **setgroups**() system call does not. Please consult the [initgroups(3)](/initgroups/3.md) manual page for the rationale.