NAME

getgrent, getgrent_r, getgrgid, getgrgid_r, getgrnam, getgrnam_r, setgrent, setgrent_r, endgrent, endgrent_r, fgetgrent, fgetgrent_r − Access group information in the user database

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <grp.h>

struct group ∗getgrent(void);

int getgrent_r(
struct group ∗result,
char ∗buffer,
int len,
FILE ∗∗gr_fp);

struct group ∗getgrgid(
gid_t gid);

int getgrgid_r(
gid_t gid,
struct group ∗result,
char ∗buffer,
int len);

struct group ∗getgrnam(
const char ∗name);

int getgrnam_r(
const char ∗name,
struct group ∗result,
char ∗buffer,
int len);

int setgrent(void);

int setgrent_r(
FILE ∗∗gr_fp);

void endgrent(void);

void endgrent_r(
FILE ∗∗gr_fp);

struct group ∗fgetgrent(
FILE ∗f);

int fgetgrent_r(
FILE ∗f,
struct group ∗result,
char ∗buffer,
int len);

PARAMETERS

nameSpecifies the name of the group for which the group file entry is to be retrieved. 

gidSpecifies the group ID of the group for which the group file entry is to be retrieved. 

resultPoints to the retrieved group file entry. 

bufferSpecifies the working buffer that is able to hold the longest group entry in the database (/etc/group). 

lenSpecifies the length of buffer.  This length should be sufficient for buf to hold the longest /etc/group line. 

gr_fpSpecifies a file that contains the next group structure (initialized by the user). 

fSpecifies a file that contains the next group structure (initialized by the user).  This file should have the same format as /etc/group.  The minimum buffer size is 1024 bytes as defined for SIABUFSIZ in /usr/include/sia.h. 

lenSpecifies the length of buffer.  The minimum buffer size is 1024 bytes as defined for SIABUFSIZ in /usr/include/sia.h. 

DESCRIPTION

The getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(), and fgetgrent() functions may be used to access the basic group attributes. 

The setgrent() function opens the user database (if not already open) and rewinds to the first group entry in the database. 

The getgrent(), getgrnam(), and getgrgid() functions return information about the requested group.  The getgrent() function returns the next group in the sequential search.  The getgrnam() function returns the first group in the database with the gr_name field that matches the name parameter.  The getgrgid() function returns the first group in the database with a gr_gid field that matches the gid parameter.  The endgrent() function closes the user database. 

The group structure, which is returned by the getgrent(), getgrnam(), and getgrgid(), functions, is defined in the grp.h header file, and contains the following members:

gr_nameThe name of the group. 

gr_passwdThe password of the group.  (Note that this field is not used by the system, so its value is meaningless.) 

gr_gidThe ID of the group. 

gr_memThe members of the group. 

The fgetgrent() function gets a group file entry from the file specified by the f parameter, rather than assuming that it comes from the /etc/group file.  This file must have the format of the /etc/group file. 

The getgrgid_r(), getgrnam_r(), getgrent_r(), setgrent_r(), fgetgrent_r(), and endgrent_r() functions are the reentrant versions of getgrgid(), getgrnam(), getgrent(), setgrent(), fgetgrent(), and endgrent() respectively.  The getgrent_r(), setgrent_r(), fgetgrent_r(), and endgrent_r() functions use the f and gr_fp parameters to keep track of the calls to the getgrent_r() function, so that subsequent calls will return subsequent entries from the /etc/group file.  Upon successful completion for the getgrgid_r(), getgrnam_r(), fgetgrent_r(), and getgrent_r() functions, the result is stored in the buffer pointed to by the result parameter, with references to the working buffer. 

NOTES

The data that is returned by the getgrent(), getgrnam(), fgetgrent(), and getgrgid() functions is stored in a static area and will be overwritten on subsequent calls to these routines.  If it is to be saved, it should be copied. 

Note that the caller is expected to initialize ∗gr_fp to NULL before using it for the first time. 

Note also that entries which are excessively long will be ignored by both the reentrant and non-reentrant functions. 

If the system is configured to access the basic group attributes database through NIS, the getgrent_r() function may not produce correct results if called from multiple threads. 

AES Support Level:
Full use (getgrgid(), getgrnam()). 

RETURN VALUES

Upon successful completion, the getgrent(), getgrnam(), getgrgid(), and fgetgrent() functions return a pointer to a valid group structure containing a matching entry.  Upon failure, these functions return NULL. 

The getgrent_r(), getgrnam_r(), getgrgid_r(), and fgetgrent_r() functions return a value of 0 (zero) for success and a value of -1 for failure. 

The setgrent() function returns a a value of 1 for success and a value of 0 (zero) for failure. 

The setgrent_r() function returns a value of 0 (zero) for success and a value of -1 for failure. 

ERRORS

If any of the following conditions occurs, the getgrent_r(), getgrnam_r(), getgrgid_r(), fgetgrent_r(), and setgrent_r() functions set errno to the corresponding value:

[EINVAL]The result, gr_fp, or buffer parameter is invalid, or len is too small. 

If any of the following additional conditions occurs, the getgrent_r(), getgrnam_r(), getgrgid_r(), and fgetgrent_r() functions set errno to the corresponding value:

[ESRCH]The search failed. 

RELATED INFORMATION

Functions: getpwent(3).