getgrent(3C)

NAME

getgrent(), getgrgid(), getgrgid_r(), getgrnam(), getgrnam_r(), setgrent(), endgrent(), fgetgrent() — get group file entry

SYNOPSIS

#include <grp.h> 

struct group *getgrent(void); 

struct group *getgrgid(gid_t gid); 

int  getgrgid_r(gid_t gid, struct group *grp, char *buffer, 
           size_t buflen, struct group ** result); 

struct group *getgrnam(const char *name); 

int  getgrnam_r(const char *name, struct group *grp, char *buffer, 
           size_t buflen, struct group ** result); 

void setgrent(void); 

void endgrent(void); 

struct group *fgetgrent(FILE *stream);

Obsolescent Interfaces

#include <grp.h> 

int  getgrent_r(struct group *result, char *buffer, int buflen, 
           FILE **grfp); 

void setgrent_r(FILE **grfp); 

void endgrent_r(FILE **grfp); 

int  fgetgrent_r(FILE *stream, struct group *result, char *buffer, 
            int buflen); 

DESCRIPTION

getgrent(), getgrgid(), and getgrnam() are used to obtain group entries, and return a pointer to an object of group structure. An entry may come from any of the sources for group specified in the /etc/nsswitch.conf file. See nsswitch.conf(4).

The group structure is defined in <grp.h> and includes the following members:

char  *gr_name;    /* the name of the group */ 
char  *gr_passwd;  /* the encrypted group password */ 
gid_t gr_gid;      /* the numerical group ID */ 
char  **gr_mem;    /* null-terminated array of pointers 
                      to member names */ 

getgrent(): When first called, getgrent() returns a pointer to the first group structure in the group database; thereafter, it returns a pointer to the next group structure in the database. In this way, successive calls can be used to search the entire database;
setgrent(): Has the effect of rewinding the group database to allow repeated searches;
endgrent(): Can be called to indicate that group database processing is complete;
getgrgid(): Searches from the beginning of the group database until a numeric group ID matching gid is found, and returns a pointer to the particular structure in which it was found;
getgrnam(): Searches from the beginning of the group database until a group name matching name is found, and returns a pointer to the particular structure in which it was found;
fgetgrent(): Returns a pointer to the next group structure in the standard I/O stream stream, which should be open for reading, and its contents should match the format of /etc/group.

Obsolescent Interfaces

getgrent_r(), setgrent_r(), endgrent_r(), fgetgrent_r() get group file entry.

Reentrant Interfaces

getgrgid_r() and getgrnam_r() both update the struct group pointed to by grp and store a pointer to that structure at the location pointed to by result. The structure shall contain an entry from the group database with a matching gid or name. Storage referenced by the group structure pointed to by grp shall be allocated from the memory provided with the buffer parameter, which is buflen in size. The maximum size needed for this buffer can be determined with the _SC_GETGR_R_SIZE_MAX sysconf() parameter. A NULL pointer is returned at the location pointed to by result on error or if the requested entry is not found.

RETURN VALUE

getgrent(), getgrgid(), getgrnam(), and fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid group structure.

getgrgid_r() and getgrnam_r() return zero upon success. Otherwise, an error number is returned to indicate the error.

ERRORS

getgrent(), getgrgid(), getgrnam() and fgetgrent() fail if any of the following are true:

EIO: An I/O error has occurred.
EMFILE: OPEN_MAX file descriptors are currently open in the calling process.
ENFILE: The maximum allowable number of files is currently open in the system.

The getgrgid_r() and getgrnam_r() functions will fail if:

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

WARNINGS

The value returned by getgrent(), getgrgid(), getgrnam(), and fgetgrent() points to an area that is overwritten by each call to any of the functions. It must be copied if it is to be saved.

Users of getgrgid_r() and getgrnam_r() should note that these interfaces now conform with POSIX.1c. getgrent_r(), setgrent_r(), endgrent_r() and fgetgrent_r() are obsolescent interfaces. These interfaces and the old prototypes of getgrgid_r() and getgrnam_r() are supported for compatibility with existing DCE applications only.

The interfaces setgrent(), getgrent(), endgrent(), getgrgid(), getgrnam(), getgrgid_r() and getgrgnam_r() use the Dynamic Name Service Switch. (See nsswitch.conf(4).) An application that uses these interfaces cannot be fully archive bound.

DEPENDENCIES

NFS

Files

/var/yp/domainname/group.byname
/var/yp/domainname/group.bygid

FILES

/etc/group

STANDARDS CONFORMANCE

getgrent(): SVID2, SVID3, XPG2

endgrent(): SVID2, SVID3, XPG2

fgetgrent(): SVID2, SVID3, XPG2

getgrgid(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

getgrnam(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

setgrent(): SVID2, SVID3, XPG2

getgrnam_r(), getgrgid_r(): POSIX.1c

getgrent(3C)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Obsolescent Interfaces

DESCRIPTION

Obsolescent Interfaces

Reentrant Interfaces

RETURN VALUE

ERRORS

WARNINGS

DEPENDENCIES

NFS

Files

See Also

FILES

SEE ALSO

STANDARDS CONFORMANCE