GETPWENT(3)                          BSD                           GETPWENT(3)



NAME
     getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile - get
     password file entry

SYNOPSIS
     #include <pwd.h>

     struct passwd *getpwuid(uid)
     int uid;

     struct passwd *getpwnam(name)
     char *name;

     struct passwd *getpwent()

     setpwent()

     endpwent()

     setpwfile(name)
     char *name;

DESCRIPTION
     getpwent, getpwuid, and getpwnam return a pointer to an object with the
     following structure containing the broken-out fields of a line in the
     password file.

          /*   pwd.h     4.1  83/05/03  */

          struct    passwd { /* see getpwent(3) */
               char *pw_name;
               char *pw_passwd;
               int  pw_uid;
               int  pw_gid;
               int  pw_quota;
               char *pw_comment;
               char *pw_gecos;
               char *pw_dir;
               char *pw_shell;
          };

          #ifndef __STDC__
          struct passwd *getpwent(), *getpwuid(), *getpwnam();
          #else
          struct passwd *getpwent(void);

          struct passwd *getpwuid(
                  int     uid
                  );

          struct passwd *getpwnam(
                  char    *name
                  );
          #endif

     The fields pw_quota and pw_comment are unused; the others have meanings
     described in passwd(5).

     setpwent opens the file; endpwent closes it.  getpwuid and getpwnam
     search the file (opening it if necessary) for a matching uid or name.
     EOF is returned if there is no entry.

     For programs wishing to read the entire file, getpwent reads the next
     line (opening the file if necessary).  In addition to opening the file,
     setpwent can be used to make getpwent begin its search from the beginning
     of the file.

     setpwfile changes the default password file to name thus allowing
     alternate password files to be used.  Note that it does not close the
     previous file.  If this is desired, endpwent should be called prior to
     it.

FILES
     /etc/passwd

SEE ALSO
     getlogin(3), getgrent(3), passwd(5), rgyd(8)

DIAGNOSTICS
     The routines getpwent, getpwuid, and getpwnam return a NULL pointer (0)
     on EOF or error.

NOTES
     All information is contained in a static area, so it must be copied if it
     is to be saved.

     Under Domain/OS BSD, /etc/passwd is a read-only object of the type
     "passwd," maintained by the registry server.  See rgyd(8).  The presence
     of the registry server affects the implementation of these interfaces in
     the following way.

     If there was no call to setpwfile, these interfaces call the registry
     server.  If this call fails, they search the local registry.

     If there was a call to setpwfile, these interfaces search name.  They
     access name by way of its type manager.  If name is of type "passwd" (as
     in the case of /etc/passwd), its manager will cause the interface to call
     the registry server.  If, in this case, the call to the registry server
     fails, the local registry will not be searched.  name remains in effect
     until the next call to setpwfile or the process fails.