'\"! tbl | mmdoc
'\"macro stdmacro
.if n .pH g3c.getgrent @(#)getgrent	40.17 of 10/25/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getgrent 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} getgrent 3C "C Programming Language Utilities"
.if \nX=2 .ds x} getgrent 3C "" "\&"
.if \nX=3 .ds x} getgrent "" "" "\&"
.TH \*(x}
.SH NAME
\f4getgrent\f1, \f4getgrgid\f1, \f4getgrnam\f1\^, \f4setgrent\f1, \f4endgrent\f1, \f4fgetgrent\f1 \- get group file entry
.SH SYNOPSIS
\f4#include <grp.h>\f1
.PP
\f4struct group \(**getgrent (void);\f1
.PP
\f4struct group \(**getgrgid (gid_t gid);\f1
.PP
\f4struct group \(**getgrnam (const char \(**name);\f1
.PP
\f4void setgrent (void);\f1
.PP
\f4void endgrent (void);\f1
.PP
\f4struct group \(**fgetgrent (\s-1FILE\s+1  \(**f);\f1
.SH DESCRIPTION
\f4getgrent\fP,
\f4getgrgid\fP,
and
\f4getgrnam\fP
each return pointers
to an object
containing the broken-out
fields of a line in the
\f4/etc/group\f1
file.
Each line contains a ``group'' structure, defined in the
\f4grp.h\fP
header file with the following members:
.RS
.TS
l1f4 l1f4 l1f4 lf4.
	char	\(**gr_name;	/\(** the name of the group \(**/
	char	\(**gr_passwd;	/\(** the encrypted group password \(**/
	gid_t	gr_gid;	/\(** the numerical group \s-1ID\s+1 \(**/
	char	\(**\(**gr_mem;	/\(** vector of pointers to member names \(**/\f1
.TE
.RE
When first called,
\f4getgrent\fP
returns a pointer to the first group structure in the file;
thereafter, it returns a pointer to the next group structure in the file;
so, successive calls may be
used to search the entire file.
\f4getgrgid\fP
searches from the beginning of the file until a numerical group id
matching
.I gid\^
is found and returns a pointer to the particular structure in which 
it was found.
.PP
\f4getgrnam\fP
searches from the beginning of the file until a group name matching
.I name\^
is found and returns a
pointer to the particular structure in which it was found.
If an end-of-file or an error
is encountered on reading, these functions return a
null pointer.
.PP
A call to
\f4setgrent\fP
has the effect of rewinding
the group file
to allow
repeated searches.
\f4endgrent\fP
may be called to
close the group file
when processing is complete.
.PP
\f4fgetgrent\fP
returns a pointer to the next group structure in the stream
.IR f ,
which matches the format of
\f4/etc/group\f1.
.SH FILES
\f4/etc/group\f1
.SH "SEE ALSO"
\f4getlogin\fP(3C), \f4getpwent\fP(3C).
.br
\f4group\fP(4) in the \f2System Administrator's Reference Manual\f1.
.bp
.SH DIAGNOSTICS
\f4getgrent\f1,
\f4getgrgid\f1,
\f4getgrnam\f1\^,
and
\f4fgetgrent\f1
return
a null pointer on
\f4EOF\f1
or error.
.SH NOTES
All information
is contained in a static area,
so it must be copied if it is
to be saved.
.\"	@(#)getgrent.3c	6.3 of 10/20/83
.Ee
