usr/src/lib/libc/gen/getpwent.3

.\"	@(#)getpwent.3	6.3 (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 *getpwuid(uid)
.B int uid;
.PP
.B struct passwd *getpwnam(name)
.B char *name;
.PP
.B struct passwd *getpwent()
.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
Searching of the password file is done using the \fIndbm\fP
database access routines.
.I Setpwent
opens the database;
.I endpwent
closes it.
.I Getpwuid
and
.I getpwnam
search the database (opening it if necessary) for a matching
.I uid
or
.IR name .
EOF is returned if there is no entry.
.PP
For programs wishing to read the entire database,
.I getpwent
reads the next
line (opening the database if necessary).
In addition to opening the database,
.I setpwent
can be used to make
.I getpwent
begin its search from the beginning of the database.
.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.
.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
	1	.\" @(#)getpwent.3 6.3 (Berkeley) %G%
	2	.\"
	3	.TH GETPWENT 3 ""
	4	.AT 3
	5	.SH NAME
	6	getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file entry
	7	.SH SYNOPSIS
	8	.nf
	9	.B #include <pwd.h>
	10	.PP
	11	.B struct passwd *getpwuid(uid)
	12	.B int uid;
	13	.PP
	14	.B struct passwd *getpwnam(name)
	15	.B char *name;
	16	.PP
	17	.B struct passwd *getpwent()
	18	.PP
	19	.B setpwent()
	20	.PP
	21	.B endpwent()
	22	.PP
	23	.B setpwfile(name)
	24	.B char *name;
	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	Searching of the password file is done using the \fIndbm\fP
	52	database access routines.
	53	.I Setpwent
	54	opens the database;
	55	.I endpwent
	56	closes it.
	57	.I Getpwuid
	58	and
	59	.I getpwnam
	60	search the database (opening it if necessary) for a matching
	61	.I uid
	62	or
	63	.IR name .
	64	EOF is returned if there is no entry.
	65	.PP
	66	For programs wishing to read the entire database,
	67	.I getpwent
	68	reads the next
	69	line (opening the database if necessary).
	70	In addition to opening the database,
	71	.I setpwent
	72	can be used to make
	73	.I getpwent
	74	begin its search from the beginning of the database.
	75	.PP
	76	.I Setpwfile
	77	changes the default password file to
	78	.I name
	79	thus allowing alternate password files to be used.
	80	Note that it does
	81	.I not
	82	close the previous file.
	83	If this is desired,
	84	.I endpwent
	85	should be called prior to it.
	86	.SH FILES
	87	/etc/passwd
	88	.SH "SEE ALSO"
	89	getlogin(3), getgrent(3), passwd(5)
	90	.SH DIAGNOSTICS
	91	The routines
	92	.IR getpwent ,
	93	.IR getpwuid ,
	94	and
	95	.IR getpwnam ,
	96	return a null pointer (0) on EOF or error.
	97	.SH BUGS
	98	All information
	99	is contained in a static area
	100	so it must be copied if it is
	101	to be saved.