GETGRENT(3)

NAME
getgrent, getgrnam, getgrgid, setgrent, endgrent, setgrfile - group file routines

SYNOPSIS
#include <grp.h>
struct group *getgrent(void)
struct group *getgrnam(const char *name)
struct group *getgrgid(gid_t gid)
int setgrent(void)
void endgrent(void)
void setgrfile(const char *file)

DESCRIPTION
These functions are used to obtain information from the group file. They return this information in a struct group as defined by <grp.h>:

struct group {
	char	*gr_name;	/* login name */
	char	*gr_passwd;	/* encrypted password */
	gid_t	gr_gid;	/* numeric group id */
	char	**gr_mem;	/* null-terminated list of group members */
};

Getgrent() reads the group file entry by entry. Getgrnam() scans the entire group file for the group with the given name. Getgrgid() looks for the first group with the given gid. The setgrent() and endgrent() functions are used to open and later close the group file. With setgrfile() one can specify the file to read other than the normal group file. This only sets the name, the next setgrent() call will open the file. Do not touch the file name while it is active. Use setgrfile(NULL) to revert back to the normal group file.

The usual way to scan the group file is (error checking omitted):

    setgrent();
    while ((gr = getgrent()) != NULL)
    	if (appropriate_test(gr)) break;
    endgrent();

The gr variable contains the entry that is wanted if non-NULL. The getgrnam() and getgrgid() functions are implemented as in this example, with error checking of course.

Getgrent() calls setgrent() if this has not yet been done. Setgrent() first calls endgrent() if the group file is still open. (Other implementations may simply rewind the file.)

FILES

/etc/group
    The group file database.

SEE ALSO
getgroups(2), initgroups(3), getpwent(3), passwd(5).

DIAGNOSTICS
Setgrent() has the same return value and error codes as the open(2) call it uses to open the group file. The getxxx() functions return NULL on end of file, entry not found, or error. You can set errno to zero before the call and check it after.

NOTES
All getxxx() routines return a pointer to static storage that is overwritten in each call.

Only getgrnam() and getgrgid() are defined by POSIX. The _MINIX_SOURCE macro must be defined before including <grp.h> to make the other functions visible. The gr_passwd field is also not defined by POSIX, but is always visible. Portable code cannot reliably detect errors by setting errno to zero. Under Minix it is better to make a getgrent() scan if you need to look up several group-id's or names, but portable code had better use several getgrgid() or getgrnam() calls. The getgrent() is usually available on other systems, but may be very expensive. See initgroups(3) if you are after supplementary group id's.

AUTHOR
Kees J. Bot (kjb@cs.vu.nl)