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

# getgrgid(3)

group database operations

Part of [endgrent(3)](/endgrent/3.md).

## NAME

**getgrent**, **getgrent\_r**, **getgrnam**, **getgrnam\_r**, **getgrgid**, **getgrgid\_r**, **setgroupent**, **setgrent**, **endgrent** – group database operations

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

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

*struct* *group* *\**\

**getgrent**(*void*);

*int*\

**getgrent\_r**(*struct group \*grp*, *char \*buffer*, *size\_t bufsize*, *struct group \*\*result*);

*struct* *group* *\**\

**getgrnam**(*const char \*name*);

*int*\

**getgrnam\_r**(*const char \*name*, *struct group \*grp*, *char \*buffer*, *size\_t bufsize*, *struct group \*\*result*);

*struct* *group* *\**\

**getgrgid**(*gid\_t gid*);

*int*\

**getgrgid\_r**(*gid\_t gid*, *struct group \*grp*, *char \*buffer*, *size\_t bufsize*, *struct group \*\*result*);

*int*\

**setgroupent**(*int stayopen*);

*void*\

**setgrent**(*void*);

*void*\

**endgrent**(*void*);

## DESCRIPTION

These functions operate on the group database file */etc/group* which is described in [group(5)](/group/5.md). Each line of the database is defined by the structure *group* found in the include file ⟨grp.h⟩:

```
struct group {
	char	*gr_name;	/* group name */
	char	*gr_passwd;	/* group password */
	gid_t	gr_gid;		/* group id */
	char	**gr_mem;	/* group members */
};
```

The functions **getgrnam**() and **getgrgid**() search the group database for the given group name pointed to by *name* or the group id pointed to by *gid*, respectively, returning the first one encountered. Identical group names or group gids may result in undefined behavior.

The **getgrent**() function sequentially reads the group database and is intended for programs that wish to step through the complete list of groups.

The functions **getgrent\_r**(), **getgrnam\_r**(), and **getgrgid\_r**() are thread-safe versions of **getgrent**(), **getgrnam**(), and **getgrgid**(), respectively. The caller must provide storage for the results of the search in the *grp*, *buffer*, *bufsize*, and *result* arguments. When these functions are successful, the *grp* argument will be filled-in, and a pointer to that argument will be stored in *result*. If an entry is not found or an error occurs, *result* will be set to NULL.

These functions will open the group file for reading, if necessary.

The **setgroupent**() function opens the file, or rewinds it if it is already open. If *stayopen* is non-zero, file descriptors are left open, significantly speeding functions subsequent calls. This functionality is unnecessary for **getgrent**() as it does not close its file descriptors by default. It should also be noted that it is dangerous for long-running programs to use this functionality as the group file may be updated.

The **setgrent**() function is identical to **setgroupent**() with an argument of zero.

The **endgrent**() function closes any open files.

## RETURN VALUES

The functions **getgrent**(), **getgrnam**(), and **getgrgid**(), return a pointer to a group structure on success or NULL if the entry is not found or if an error occurs. If an error does occur, *errno* will be set. Note that programs must explicitly set *errno* to zero before calling any of these functions if they need to distinguish between a non-existent entry and an error. The functions **getgrent\_r**(), **getgrnam\_r**(), and **getgrgid\_r**() return 0 if no error occurred, or an error number to indicate failure. It is not an error if a matching entry is not found. (Thus, if *result* is set to NULL and the return value is 0, no matching entry exists.)

The function **setgroupent**() returns the value 1 if successful, otherwise the value 0 is returned. The functions **endgrent**(), **setgrent**() and **setgrfile**() have no return value.

## FILES

- */etc/group*

  group database file

## COMPATIBILITY

The historic function **setgrfile**(), which allowed the specification of alternate password databases, has been deprecated and is no longer available.

## SEE ALSO

[getpwent(3)](/getpwent/3.md), [group(5)](/group/5.md), [nsswitch.conf(5)](/nsswitch.conf/5.md), [yp(8)](/yp/8.md)

## STANDARDS

The **getgrent**(), **getgrnam**(), **getgrnam\_r**(), **getgrgid**(), **getgrgid\_r**() and **endgrent**() functions conform to ISO/IEC 9945-1:1996 (“POSIX.1”). The **setgrent**() function differs from that standard in that its return type is *int* rather than *void*.

## HISTORY

The functions **endgrent**(), **getgrent**(), **getgrnam**(), **getgrgid**(), and **setgrent**() appeared in Version 7 AT&T UNIX. The functions **setgrfile**() and **setgroupent**() appeared in 4.3BSD-Reno. The functions **getgrent\_r**(), **getgrnam\_r**(), and **getgrgid\_r**() appeared in FreeBSD 5.1.

## BUGS

The functions **getgrent**(), **getgrnam**(), **getgrgid**(), **setgroupent**() and **setgrent**() leave their results in an internal static object and return a pointer to that object. Subsequent calls to the same function will modify the same object.

The functions **getgrent**(), **getgrent\_r**(), **endgrent**(), **setgroupent**(), and **setgrent**() are fairly useless in a networked environment and should be avoided, if possible. The **getgrent**() and **getgrent\_r**() functions make no attempt to suppress duplicate information if multiple sources are specified in [nsswitch.conf(5)](/nsswitch.conf/5.md).