[unix-history] / usr / src / lib / libc / gen / getgrent.3

.\"	@(#)getgrent.3	6.2 (Berkeley) %G%
.\"
.TH GETGRENT 3  ""
.AT 3
.SH NAME
getgrent, getgrgid, getgrnam, setgrent, endgrent \- get group file entry
.SH SYNOPSIS
.nf
.B #include <grp.h>
.PP
.B struct group *getgrent()
.PP
.B struct group *getgrgid(gid)
.B int gid;
.PP
.B struct group *getgrnam(name)
.B char *name;
.PP
.B setgrent()
.PP
.B endgrent()
.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.
.RS
.PP
.nf
.so /usr/include/grp.h
.fi
.RE
.PP
The members of this structure are:
.TP \w'gr_passwd'u+2n
gr_name
The name of the group.
.br
.ns
.TP \w'gr_passwd'u+2n
gr_passwd
The encrypted password of the group.
.br
.ns
.TP \w'gr_passwd'u+2n
gr_gid
The numerical group-ID.
.br
.ns
.TP \w'gr_passwd'u+2n
gr_mem
Null-terminated vector
of pointers to the individual
member names.
.PP
.I Getgrent
simply reads the next
line while
.I getgrgid
and
.I getgrnam
search until a matching
.I gid
or
.I name
is found
(or until EOF is encountered).
Each routine picks up
where the others leave off
so successive calls may be used
to search the entire file.
.PP
A call to
.I setgrent
has the effect of rewinding
the group file
to allow
repeated searches.
.I Endgrent
may be called to
close the group file
when processing is complete.
.SH FILES
/etc/group
.SH "SEE ALSO"
getlogin(3), getpwent(3), group(5)
.SH DIAGNOSTICS
A null pointer
(0) is returned on EOF or error.
.SH BUGS
All information
is contained in a static area
so it must be copied if it is
to be saved.
Commit	Line	Data
792b7b2c	1	.\" @(#)getgrent.3 6.2 (Berkeley) %G%
6c9d675c	2	.\"
6548329e	3	.TH GETGRENT 3 ""
6c9d675c KM	4	.AT 3
	5	.SH NAME
	6	getgrent, getgrgid, getgrnam, setgrent, endgrent \- get group file entry
	7	.SH SYNOPSIS
	8	.nf
	9	.B #include <grp.h>
	10	.PP
	11	.B struct group *getgrent()
	12	.PP
	13	.B struct group *getgrgid(gid)
	14	.B int gid;
	15	.PP
	16	.B struct group *getgrnam(name)
	17	.B char *name;
	18	.PP
	19	.B setgrent()
	20	.PP
	21	.B endgrent()
	22	.fi
	23	.SH DESCRIPTION
	24	.I Getgrent,
	25	.I getgrgid
	26	and
	27	.I getgrnam
	28	each return pointers
	29	to an object
	30	with the following structure
	31	containing the broken-out
	32	fields of a line in the group file.
	33	.RS
	34	.PP
	35	.nf
	36	.so /usr/include/grp.h
	37	.fi
	38	.RE
	39	.PP
	40	The members of this structure are:
	41	.TP \w'gr_passwd'u+2n
	42	gr_name
	43	The name of the group.
	44	.br
	45	.ns
	46	.TP \w'gr_passwd'u+2n
	47	gr_passwd
	48	The encrypted password of the group.
	49	.br
	50	.ns
	51	.TP \w'gr_passwd'u+2n
	52	gr_gid
	53	The numerical group-ID.
	54	.br
	55	.ns
	56	.TP \w'gr_passwd'u+2n
	57	gr_mem
	58	Null-terminated vector
	59	of pointers to the individual
	60	member names.
	61	.PP
	62	.I Getgrent
	63	simply reads the next
	64	line while
	65	.I getgrgid
	66	and
	67	.I getgrnam
68	search until a matching
69	.I gid
70	or
71	.I name
72	is found
73	(or until EOF is encountered).
74	Each routine picks up
75	where the others leave off
76	so successive calls may be used
77	to search the entire file.
78	.PP
79	A call to
80	.I setgrent
81	has the effect of rewinding
82	the group file
83	to allow
84	repeated searches.
85	.I Endgrent
86	may be called to
87	close the group file
88	when processing is complete.
89	.SH FILES
90	/etc/group
91	.SH "SEE ALSO"
92	getlogin(3), getpwent(3), group(5)
93	.SH DIAGNOSTICS
94	A null pointer
95	(0) is returned on EOF or error.
96	.SH BUGS
97	All information
98	is contained in a static area
99	so it must be copied if it is
100	to be saved.