4.3BSD/usr/man/man3/getpwent.3

.\"	@(#)getpwent.3	6.3 (Berkeley) 5/15/86
.\"
.TH GETPWENT 3  "May 15, 1986"
.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.