GETPWENT(3)                    Library Routines                    GETPWENT(3)




NAME

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


SYNOPSIS

       #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);
       int setpwent (void);
       void endpwent (void);


DESCRIPTION

       These  functions  operate  on  the  password  database  file  which  is
       described  in  passwd(5).  Each entry in the database is defined by the
       structure 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;     /* real name */
            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 uid, respectively, always returning the
       first one encountered.

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

       The setpassent function 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.

       The  setpwent  function  is identical 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,  the
       encrypted  password  will be returned, otherwise, the password field of
       the returned structure will point to the string *.


YP/NIS INTERACTION

       When the yp(4) password database is enabled, the getpwnam and  getpwuid
       functions use the YP maps passwd.byname and passwd.byuid, respectively,
       if the requested password entry is not found  in  the  local  database.
       The getpwent function will step through the YP map passwd.byname if the
       entire map is enabled as described in passwd(5).


RETURN VALUES

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


FILES

       /etc/pwd.db
              The insecure password database file

       /etc/spwd.db
              The secure password database file

       /etc/master.passwd
              The current password file

       /etc/passwd
              A Version 7 format password file


SEE ALSO

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


HISTORY

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


COMPATIBILITY

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


BUGS

       The functions getpwent, getpwnam, and getpwuid, leave their results  in
       an  internal  static object and return a pointer to that object. Subse-
       quent calls to the same function will modify the same object.



GNO                           September 20, 1994                   GETPWENT(3)

Man(1) output converted with man2html