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 imple-
     mented 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 3 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)