getpwent(3)

NAME
     getpwent, getpwnam, getpwuid, setpwent, endpwent,  setpwfile  -  password
     file routines

SYNOPSIS
     #include <pwd.h>

     struct passwd *getpwent(void)
     struct passwd *getpwnam(const char *name)
     struct passwd *getpwuid(uid_t uid)
     int setpwent(void)
     void endpwent(void)
     void setpwfile(const char *file)

DESCRIPTION
     These functions are used to obtain information from  the  password  file.
     They return this information in a struct passwd 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 */
     };

     Getpwent() reads the password file entry by entry.  Getpwnam() scans  the
     entire  password file for the user with the given name.  Getpwuid() looks
     for the first user with the given uid.   The  setpwent()  and  endpwent()
     functions  are  used  to  open  and  later close the password file.  With
     setpwfile() one can specify the  file  to  read  other  than  the  normal
     password  file.   This  only sets the name, the next setpwent() call will
     open the file.  Do not touch the file  name  while  it  is  active.   Use
     setpwfile(NULL) 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 pw variable contains the entry  that  is  wanted  if  non-NULL.   The
     getpwnam()  and  getpwuid() functions are implemented as in this example,
     with error checking of course.



     Getpwent() calls setpwent() if this has not yet  been  done.   Setpwent()
     first  calls  endpwent()  if  the  password  file  is still open.  (Other
     implementations may simply rewind the file.)

FILES

     /etc/passwd    The password file database.

SEE ALSO
     cuserid(3), getlogin(3), getgrent(3), passwd(5).

DIAGNOSTICS
     Setpwent() has the same return value and error codes as the open(2)  call
     it uses to open the password file.  The getxxx() functions return NULL on
     end of file, entry not found, or error.  You can set errno to zero before
     the call and check it after.

NOTES
     All getxxx()  routines  return  a  pointer  to  static  storage  that  is
     overwritten in each call.

     Only getpwnam() and getpwuid() are defined by POSIX.   The  _MINIX_SOURCE
     macro  must  be  defined  before  including  <pwd.h>  to  make  the other
     functions visible.  The  pw_passwd  and  pw_gecos  fields  are  also  not
     defined  by POSIX, but are always visible.  Portable code cannot reliably
     detect errors by setting errno to zero.  Under Minix it is better to make
     a  getpwent() scan if you need to look up several user-id's or names, but
     portable code had better use several getpwuid() or getpwnam() calls.  The
     getpwent()  is  usually  available  on  other  systems,  but  may be very
     expensive.

AUTHOR
     Kees J. Bot (kjb@cs.vu.nl)