NAME    [Toc]    [Back]

     getpwent, getpwnam, getpwuid, setpassent, setpwent, endpwent
- password
     database operations

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <pwd.h>

     struct passwd *
     getpwent(void);

     struct passwd *
     getpwnam(const char *login);

     struct passwd *
     getpwuid(uid_t uid);

     int
     setpassent(int stayopen);

     void
     setpwent(void);

     void
     endpwent(void);

DESCRIPTION    [Toc]    [Back]

     These  functions operate on the password database file which
is described
     in passwd(5).  Each entry in the database is defined by  the
structure
     struct passwd found in the include file <pwd.h>:

           struct passwd {
                   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
*/
           };

     The functions getpwnam() and getpwuid() search the  password
database for
     the  given  login  name or user ID, respectively, always returning the first
     one encountered.

     getpwent() sequentially reads the password database  and  is
intended for
     programs that wish to process the complete list of users.

     setpassent()  accomplishes  two  purposes.  First, it causes
getpwent() to
     ``rewind'' to the beginning of the database.   Additionally,
if stayopen
     is  non-zero,  file descriptors are left open, significantly
speeding up
     subsequent accesses for all of the routines.   (This  latter
functionality
     is  unnecessary  for getpwent() as it doesn't close its file
descriptors by
     default.)

     It is dangerous for long-running programs to keep  the  file
descriptors
     open as the database will become out of date if it is updated while the
     program is running.

     setpwent() is equivalent to setpassent() with an argument of
zero.

     The endpwent() function closes any open files.

     These  routines have been written to ``shadow'' the password
file, e.g.,
     allow only certain programs to have access to the  encrypted
password.  If
     the  process  which  calls them has an effective UID of 0 or
has the
     ``_shadow'' group in its group vector, the  encrypted  password will be returned,
 otherwise, the password field of the returned structure will
     point to the string `*'.

RETURN VALUES    [Toc]    [Back]

     The functions getpwent(), getpwnam(), and getpwuid()  return
a valid
     pointer  to  a passwd structure on success or a null pointer
if end-of-file
     is reached or an error occurs.   The  setpassent()  function
returns 0 on
     failure  or  1  on  success.   The endpwent() and setpwent()
functions have no
     return value.

FILES    [Toc]    [Back]

     /etc/pwd.db         insecure password database file
     /etc/spwd.db        secure password database file
     /etc/master.passwd  current password file
     /etc/passwd         a Version 7 format password file

SEE ALSO    [Toc]    [Back]

     getlogin(2), getgrent(3), pw_dup(3), passwd(5), pwd_mkdb(8),
vipw(8)

HISTORY    [Toc]    [Back]

     The  getpwent(),  getpwnam(),  getpwuid(),  setpwent(),  and
endpwent() functions
 appeared in Version 7  AT&T  UNIX.   The  setpassent()
function appeared
 in 4.3BSD-Reno.

     The historic function setpwfile(3), which allowed the specification of
     alternate password databases, has been deprecated and is  no
longer available.

BUGS    [Toc]    [Back]

     The  functions  getpwent(), getpwnam(), and getpwuid() leave
their results
     in an internal static object and return a  pointer  to  that
object.  Subsequent
  calls  to any of these functions will modify the same
object.

     The  routines  getpwent(),  endpwent(),  setpassent(),   and
setpwent() are
     fairly  useless  in  a  networked  environment and should be
avoided, if possible.


OpenBSD     3.6                        December     11,      1993