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

.\"	@(#)getpwent.3	6.2 (Berkeley) %G%
.\"
.TH GETPWENT 3  ""
.AT 3
.SH NAME
getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file entry
.SH SYNOPSIS
.nf
.B #include <pwd.h>
.PP
.B struct passwd *getpwent()
.PP
.B struct passwd *getpwuid(uid)
.B int uid;
.PP
.B struct passwd *getpwnam(name)
.B char *name;
.PP
.B setpwent()
.PP
.B endpwent()
.PP
.B setpwfile(name)
.B char *name;
.fi
.SH DESCRIPTION
.I Getpwent,
.I getpwuid
and
.I getpwnam
each return a pointer to an object with the
following structure
containing the broken-out
fields of a line in the password file.
.RS
.PP
.nf
.so /usr/include/pwd.h
.ft R
.ad
.fi
.RE
.PP
The fields
.I pw_quota
and
.I pw_comment
are unused; the others have meanings described in
.IR passwd (5).
.PP
.I Getpwent
reads the next
line (opening the file if necessary);
.I setpwent
rewinds the file;
.I endpwent
closes it.
.PP
.I Setpwfile
changes the default password file to
.I name
thus allowing alternate password files to be used.
Note that it does
.I not
close the previous file.
If this is desired,
.I endpwent
should be called prior to it.
.PP
.I Getpwuid
and
.I getpwnam
search from the beginning until a matching
.I uid
or
.I name
is found
(or until EOF is encountered).
.SH FILES
/etc/passwd
.SH "SEE ALSO"
getlogin(3), getgrent(3), passwd(5)
.SH DIAGNOSTICS
The routines
.IR getpwent ,
.IR getpwuid ,
and
.IR getpwnam ,
return a null pointer (0) 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
c5892565	1	.\" @(#)getpwent.3 6.2 (Berkeley) %G%
4e6e003a	2	.\"
3fb9eae6	3	.TH GETPWENT 3 ""
4e6e003a KM	4	.AT 3
4e6e003a KM	5	.SH NAME
3fb9eae6	6	getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file entry
4e6e003a KM	7	.SH SYNOPSIS
	8	.nf
	9	.B #include <pwd.h>
	10	.PP
	11	.B struct passwd *getpwent()
	12	.PP
	13	.B struct passwd *getpwuid(uid)
	14	.B int uid;
	15	.PP
	16	.B struct passwd *getpwnam(name)
	17	.B char *name;
	18	.PP
c5892565	19	.B setpwent()
4e6e003a	20	.PP
c5892565	21	.B endpwent()
3fb9eae6 KM	22	.PP
	23	.B setpwfile(name)
	24	.B char *name;
4e6e003a KM	25	.fi
	26	.SH DESCRIPTION
	27	.I Getpwent,
	28	.I getpwuid
	29	and
	30	.I getpwnam
	31	each return a pointer to an object with the
	32	following structure
	33	containing the broken-out
	34	fields of a line in the password file.
	35	.RS
	36	.PP
	37	.nf
	38	.so /usr/include/pwd.h
	39	.ft R
	40	.ad
	41	.fi
	42	.RE
	43	.PP
	44	The fields
	45	.I pw_quota
	46	and
	47	.I pw_comment
	48	are unused; the others have meanings described in
	49	.IR passwd (5).
	50	.PP
	51	.I Getpwent
	52	reads the next
	53	line (opening the file if necessary);
	54	.I setpwent
	55	rewinds the file;
	56	.I endpwent
	57	closes it.
	58	.PP
3fb9eae6 KM	59	.I Setpwfile
	60	changes the default password file to
	61	.I name
	62	thus allowing alternate password files to be used.
	63	Note that it does
	64	.I not
	65	close the previous file.
	66	If this is desired,
	67	.I endpwent
	68	should be called prior to it.
	69	.PP
4e6e003a KM	70	.I Getpwuid
	71	and
	72	.I getpwnam
	73	search from the beginning until a matching
	74	.I uid
	75	or
	76	.I name
	77	is found
	78	(or until EOF is encountered).
	79	.SH FILES
	80	/etc/passwd
	81	.SH "SEE ALSO"
	82	getlogin(3), getgrent(3), passwd(5)
	83	.SH DIAGNOSTICS
c5892565 KM	84	The routines
	85	.IR getpwent ,
	86	.IR getpwuid ,
	87	and
	88	.IR getpwnam ,
	89	return a null pointer (0) on EOF or error.
4e6e003a KM	90	.SH BUGS
	91	All information
	92	is contained in a static area
	93	so it must be copied if it is
	94	to be saved.