.\" Copyright (c) 1988 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)getgrent.3	6.3 (Berkeley) %G%
.\"
.TH GETGRENT 3  ""
.AT 3
.SH NAME
getgrent, getgrgid, getgrnam, setgrent, endgrent setgrfile \- get group file entry
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <grp.h>
.PP
.B struct group *getgrent()
.PP
.B struct group *getgrgid(gid)
.B gid_t gid;
.PP
.B struct group *getgrnam(name)
.B char *name;
.PP
.B setgrent()
.PP
.B void endgrent()
.PP
.B void setgrfile(name)
.B char *name;
.fi
.SH DESCRIPTION
.I Getgrent,
.I getgrgid
and
.I getgrnam
each return pointers to an object with the following structure
containing the broken-out fields of a line in the group file,
as described in
.IR < grp.h > .
.RS
.PP
.nf
struct	group {
	char	*gr_name;
	char	*gr_passwd;
	gid_t	gr_gid;
	char	**gr_mem;
};
.ft R
.ad
.fi
.RE
.PP
The fields have meanings described in
.IR grp (5).
.PP
.I Setgrfile
changes the default group file to
.IR name ,
thus allowing usage of alternate group files.
.PP
.I Setgrent
opens the file (closing any previously opened file) or rewinds it
if it it already open.
.PP
.I Endgrent
closes any open files.
.PP
.I Getgrgid
and
.I getgrnam
search the entire file (opening it if necessary) for a matching
.I gid
or
.IR name .
.PP
For programs wishing to read the entire database,
.I getgrent
reads the next entry (opening the file if necessary).
.SH FILES
/etc/group
.SH "SEE ALSO"
getlogin(3), getpwent(3), group(5)
.SH DIAGNOSTICS
The routines
.IR getgrent ,
.IR getgruid ,
and
.IR getgrnam ,
return a null pointer (0) on EOF or error.
.I Setgrent
returns 0 on failure, 1 on success.
.I Endgrent
and
.I setgrfile
have no return value.
.SH BUGS
All information is contained in a static area so it must be
copied if it is to be saved.