getpwent(3C)                                         getpwent(3C)



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

SYNOPSIS
     #include <pwd.h>

     struct passwd *getpwent()

     struct passwd *getpwuid(uid)
     uid_t uid;

     struct passwd *getpwnam(name)
     char *name;

     void setpwent()

     void endpwent()

     setpwfile(file)
     char *name;

     struct passwd *fgetpwent(f)
     FILE *f;

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 /etc/passwd file.  Each line in
     the file contains a passwd structure, declared in the
     <pwd.h> header file:

        struct passwd {
             char *pw_name;
             char *pw_passwd;
             int  pw_uid;
             int  pw_gid;
             char *pw_age;
             char *pw_comment;
             char *pw_gecos;
             char *pw_dir;
             char *pw_shell;
        };

     Because this structure is declared in <pwd.h>, you do not
     have to redeclare it.

     The pw_comment field is unused; the others have meanings
     described in passwd(4).

     When first called, getpwent returns a pointer to the first
     passwd structure in the file.  Thereafter, it returns a



January 1992                                                    1

getpwent(3C)                                         getpwent(3C)



     pointer to the next passwd structure in the file; therefore,
     you can use a series of calls to search the entire file.
     getpwuid searches from the beginning of the file until a
     numeric user ID matching uid is found; it returns a pointer
     to the particular structure in which the match was found.
     getpwnam searches from the beginning of the file until a
     login name matching name is found; it returns a pointer to
     the particular structure in which the match was found.  If
     an end-of-file character or an error is encountered on
     reading, these functions return a NULL pointer.

     A call to setpwent has the effect of rewinding the password
     file to allow repeated searches.  You can call endpwent to
     close the password file when processing is complete.

     setpwfile changes the default password file to name, thus
     allowing the use of alternative password files. Note that
     setpwfile does not close the previous password file.  If you
     want to close this file, call endpwent before calling
     setpwfile.

     fgetpwent returns a pointer to the next passwd structure in
     the stream f, which matches the format of /etc/passwd.

STATUS MESSAGES AND VALUES
     If an end-of-file character or an error is encountered, a
     NULL pointer is returned.

WARNINGS
     The routines use <stdio.h>.  Therefore the size of programs
     not otherwise using standard I/O is increased more than
     might be expected.

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

FILES
     /etc/passwd
          File containing user information

SEE ALSO
     getgrent(3C), getlogin(3C), putpwent(3C), cuserid(3S),
     passwd(4)











2                                                    January 1992