NAME

endgrent, getgrent, setgrent - group database entry functions

 SYNOPSIS

#include <grp.h>

void endgrent(void);
struct group *getgrent(void);
void setgrent(void);

 DESCRIPTION

The getgrent() function returns a pointer to a structure containing the broken-out fields of an entry in the group database. When first called, getgrent() returns a pointer to a group structure containing the first entry in the group database. Thereafter, it returns a pointer to a group structure containing the next group structure in the group database, so successive calls may be used to search the entire database.

The setgrent() function effectively rewinds the group database to allow repeated searches.

The endgrent() function may be called to close the group database when processing is complete.

These interfaces need not be reentrant.

 RETURN VALUE

When first called, getgrent() will return a pointer to the first group structure in the group database. Upon subsequent calls it returns the next group structure in the group database. The getgrent() function returns a null pointer on end-of-file or an error and errno may be set to indicate the error.

The return value may point to a static area which is overwritten by a subsequent call to getgrgid(), getgrnam() or getgrent().

 ERRORS

The getgrent() function may fail if:

[EINTR]

A signal was caught during the operation.

[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.

 EXAMPLES

None.

 APPLICATION USAGE

These functions are provided due to their historical usage. Applications should avoid dependencies on fields in the group database, whether the database is a single file, or where in the filesystem namespace the database resides. Applications should use getgrnam() and getgrgid() whenever possible both because it avoids these dependencies and for greater portability with systems that conform to earlier versions of this specification.

 FUTURE DIRECTIONS

None.

 SEE ALSO

getgrgid(), getgrnam(), getlogin(), getpwent(), <grp.h>.