.\" Copyright (c) 1988 The Regents of the University of California.
.\" %sccs.include.redist.man%
.\" @(#)getpwent.3 6.6 (Berkeley) %G%
getpwent, getpwnam, getpwuid, setpassent,
setpwfile, setpwent, endpwent \- get password file entries
.B #include <sys/types.h>
.B struct passwd *getpwent()
.B struct passwd *getpwnam(login)
.B struct passwd *getpwuid(uid)
.B int setpassent(stayopen)
each return a pointer to a structure containing the broken-out
fields of a line in the password file. This structure is defined
and contains the following fields:
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
uid_t pw_uid; /* user uid */
gid_t pw_gid; /* user gid */
time_t pw_change; /* password change time */
char *pw_class; /* user access class */
char *pw_gecos; /* Honeywell login info */
char *pw_dir; /* home directory */
char *pw_shell; /* default shell */
time_t pw_expire; /* account expiration */
These fields are more completely described in
search the password database for a matching user name or user uid,
respectively, returning the first one encountered. Identical
user names or user uids may result in undefined behavior.
sequentially reads the password database and is intended for programs
that wish to step through the complete list of users.
All three routines will open the password file for reading, if
changes the default password file to
thus allowing the use of alternate password files.
opens the file or rewinds it if it is already open. If
is non-zero, file descriptors are left open, significantly speeding
up subsequent calls. This functionality is unnecessary for
as it doesn't close its file descriptors by default. It should also
be noted that it is dangerous for long-running programs to use this
functionality as the password file may be updated by
with an argument of zero.
These routines have been written to ``shadow'' the password file, e.g.
allow only certain programs to have access to the encrypted password.
This is done by using the
databases that correspond to the password file, with the single exception
that, rather than storing the encrypted password in the database, it stores
the offset in the password file where the encrypted password may be found.
files in preference to the ``real'' password files, only reading the
password file itself, to obtain the encrypted password, if the process
is running with an effective user id equivalent to super-user.
If the password file itself is protected, and the
files are not, this makes the password available only to programs
running with super-user privileges.
getlogin(3), getgrent(3), ndbm(3), passwd(5)
return a null pointer on EOF or error.
return 0 on failure and 1 on success.
All information is contained in a static buffer which is overwritten
by each new call. It must be copied elsewhere to be retained.
to require that file descriptors be left open, may result
are fairly useless in a networked environment and should be