getgrgid(), getgrgid_r(), getgrnam(), getgrnam_r()

search group database for matching group ID or name 

Function

SYNOPSIS

#include <sys/types.h>

#include <grp.h>

struct group *getgrgid(gid_t gid);

int getgrgid_r(gid_t gid, 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);

DESCRIPTION

The getgrgid() routine searches the group database for an entry with a matching group ID. If found, it returns a pointer to a structure with information about that group. This function is not reentrant.

The getgrgid_r() routine searches the group database for an entry with a matching group ID. If found, it fills in the group structure using the specified buffer, and returns a pointer to the structure. This function is reentrant.

The getgrnam() routine searches the group database for an entry with a matching name. If found, it returns a pointer to a structure with information about that group. This function is not reentrant.

The getgrnam_r() routine searches the group database for an entry with a matching name. If found, it fills in the group structure using the specified buffer, and returns a pointer to the structure. This function is reentrant.

The correct size for the buffer for getgrgid_r() and getgrnam_r() can be determined by calling: 

size = sysconf(_SC_GETGR_R_SIZE_MAX);

PARAMETERS

gid 

Is the group ID of the group to look up in the group database. getgrgid() and getgrgid_r() fill in the group structure with data about the group.

name 

Is the he name of the group to look up in the group database. getgrnam() and getgrnam_r() fill in the group structure with data about the group.

grp 

Points to a group structure to be filled in.

buffer 

Points to a buffer into which the data needed for the group structure members is to be placed.

bufsize 

Is the size of the buffer being passed.

result 

Is the pointer where the address of grp is to be placed on success, or NULL is to be placed on error.

RETURN VALUES

If successful, getgrgrid() and getgrnam() return a pointer to a static group structure. This structure may be overwritten by subsequent calls to getgrgid() or getgrnam().

If successful, getgrgid_r() and getgrnam_r() return 0.

If an error occurs or if the requested entry is not found, getgrgrid() and getgrnam() return a null pointer, and errno is set to one of the following values, while getgrgid_r() and getgrnam_r() return one of the following values:

EFAULT 

The name, grp, buf, or result parameter is not a valid pointer.

EINVAL 

The gid parameter is not a valid group ID, or the name parameter is not a valid group name.

ERANGE 

Insufficient storage was supplied via buffer and bufsize to contain the data to be referenced by the resulting structure.

CONFORMANCE

POSIX.1 (1996), with exceptions.

MULTITHREAD SAFETY LEVEL

getgrgid(), getgrnam(): Unsafe.

getgrgid_r(), getgrnam_r(): MT-Safe.

PORTING ISSUES

10/2016/2019/11/2022/2025 security allows only administrators and members of a group to enumerate the members of a group. Therefore, the gr_mem field of the group structure may be empty on a successful return.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
getlogin(), getlogin_r(), getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), sysconf()

Miscellaneous:
struct group

PTC MKS Toolkit 10.5 Documentation Build 40.