128 lines
4.9 KiB
HTML
128 lines
4.9 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>getpwent(3)</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>getpwent(3)</H1>
|
|
<HR>
|
|
<PRE>
|
|
|
|
</PRE>
|
|
<H2>NAME</H2><PRE>
|
|
getpwent, getpwnam, getpwuid, setpwent, endpwent, setpwfile - password
|
|
file routines
|
|
|
|
|
|
</PRE>
|
|
<H2>SYNOPSIS</H2><PRE>
|
|
<STRONG>#include</STRONG> <STRONG><pwd.h></STRONG>
|
|
|
|
<STRONG>struct</STRONG> <STRONG>passwd</STRONG> <STRONG>*getpwent(void)</STRONG>
|
|
<STRONG>struct</STRONG> <STRONG>passwd</STRONG> <STRONG>*getpwnam(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>name</EM><STRONG>)</STRONG>
|
|
<STRONG>struct</STRONG> <STRONG>passwd</STRONG> <STRONG>*getpwuid(uid_t</STRONG> <EM>uid</EM><STRONG>)</STRONG>
|
|
<STRONG>int</STRONG> <STRONG>setpwent(void)</STRONG>
|
|
<STRONG>void</STRONG> <STRONG>endpwent(void)</STRONG>
|
|
<STRONG>void</STRONG> <STRONG>setpwfile(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>file</EM><STRONG>)</STRONG>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
These functions are used to obtain information from the password file.
|
|
They return this information in a <STRONG>struct</STRONG> <STRONG>passwd</STRONG> as defined by <pwd.h>:
|
|
|
|
struct passwd {
|
|
char *pw_name; /* login name */
|
|
char *pw_passwd; /* encrypted password */
|
|
uid_t pw_uid; /* numeric user id */
|
|
gid_t pw_gid; /* numeric group id */
|
|
char *pw_gecos; /* user full name and other info */
|
|
char *pw_dir; /* user's home directory */
|
|
char *pw_shell; /* name of the user's shell */
|
|
};
|
|
|
|
<STRONG>Getpwent()</STRONG> reads the password file entry by entry. <STRONG>Getpwnam()</STRONG> scans the
|
|
entire password file for the user with the given <EM>name</EM>. <STRONG>Getpwuid()</STRONG> looks
|
|
for the first user with the given <EM>uid</EM>. The <STRONG>setpwent()</STRONG> and <STRONG>endpwent()</STRONG>
|
|
functions are used to open and later close the password file. With
|
|
<STRONG>setpwfile()</STRONG> one can specify the file to read other than the normal
|
|
password file. This only sets the name, the next <STRONG>setpwent()</STRONG> call will
|
|
open the file. Do not touch the file name while it is active. Use
|
|
<STRONG>setpwfile(NULL)</STRONG> to revert back to the normal password file.
|
|
|
|
The usual way to scan the password file is (error checking omitted):
|
|
|
|
setpwent();
|
|
while ((pw = getpwent()) != NULL)
|
|
if (appropriate_test(pw)) break;
|
|
endpwent();
|
|
|
|
The <STRONG>pw</STRONG> variable contains the entry that is wanted if non-NULL. The
|
|
<STRONG>getpwnam()</STRONG> and <STRONG>getpwuid()</STRONG> functions are implemented as in this example,
|
|
with error checking of course.
|
|
|
|
|
|
|
|
<STRONG>Getpwent()</STRONG> calls <STRONG>setpwent()</STRONG> if this has not yet been done. <STRONG>Setpwent()</STRONG>
|
|
first calls <STRONG>endpwent()</STRONG> if the password file is still open. (Other
|
|
implementations may simply rewind the file.)
|
|
|
|
|
|
</PRE>
|
|
<H2>FILES</H2><PRE>
|
|
|
|
<STRONG>/etc/passwd</STRONG> The password file database.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
<STRONG><A HREF="../man3/cuserid.3.html">cuserid(3)</A></STRONG>, <STRONG><A HREF="../man3/getlogin.3.html">getlogin(3)</A></STRONG>, <STRONG><A HREF="../man3/getgrent.3.html">getgrent(3)</A></STRONG>, <STRONG><A HREF="../man5/passwd.5.html">passwd(5)</A></STRONG>.
|
|
|
|
|
|
</PRE>
|
|
<H2>DIAGNOSTICS</H2><PRE>
|
|
<STRONG>Setpwent()</STRONG> has the same return value and error codes as the <STRONG><A HREF="../man2/open.2.html">open(2)</A></STRONG> call
|
|
it uses to open the password file. The <STRONG>get</STRONG><EM>xxx</EM><STRONG>()</STRONG> functions return NULL on
|
|
end of file, entry not found, or error. You can set <STRONG>errno</STRONG> to zero before
|
|
the call and check it after.
|
|
|
|
|
|
</PRE>
|
|
<H2>NOTES</H2><PRE>
|
|
All <STRONG>get</STRONG><EM>xxx</EM><STRONG>()</STRONG> routines return a pointer to static storage that is
|
|
overwritten in each call.
|
|
|
|
Only <STRONG>getpwnam()</STRONG> and <STRONG>getpwuid()</STRONG> are defined by POSIX. The <STRONG>_MINIX_SOURCE</STRONG>
|
|
macro must be defined before including <pwd.h> to make the other
|
|
functions visible. The <STRONG>pw_passwd</STRONG> and <STRONG>pw_gecos</STRONG> fields are also not
|
|
defined by POSIX, but are always visible. Portable code cannot reliably
|
|
detect errors by setting <STRONG>errno</STRONG> to zero. Under Minix it is better to make
|
|
a <STRONG>getpwent()</STRONG> scan if you need to look up several user-id's or names, but
|
|
portable code had better use several <STRONG>getpwuid()</STRONG> or <STRONG>getpwnam()</STRONG> calls. The
|
|
<STRONG>getpwent()</STRONG> is usually available on other systems, but may be very
|
|
expensive.
|
|
|
|
|
|
</PRE>
|
|
<H2>AUTHOR</H2><PRE>
|
|
Kees J. Bot (kjb@cs.vu.nl)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</PRE>
|
|
</BODY>
|
|
</HTML>
|