getpwent(3C)                                                   getpwent(3C)

NAME
     getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent - amend
     password file entry

SYNOPSIS
     #include <pwd.h>

     struct passwd *getpwent(void);

     struct passwd *getpwuid(uidt uid);

     struct passwd *getpwnam(const char *name);

     void setpwent(void);

     void endpwent(void);

     struct passwd *fgetpwent(FILE *f);

DESCRIPTION
     getpwent(), getpwuid(), and getpwnam() each returns 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    *pwname;
                char    *pwpasswd;
                uidt   pwuid;
                gidt   pwgid;
                char    *pwage;
                char    *pwcomment;
                char    *pwgecos;
                char    *pwdir;
                char    *pwshell;
          };

     getpwent() when first called returns a pointer to the first passwd
     structure in the file; thereafter, it returns a pointer to the next
     passwd structure in the file; so successive calls can be used to
     search the entire file. getpwuid() searches from the beginning of the
     file until a numerical user id matching uid is found and returns a
     pointer to the particular structure in which it was found. getpwnam()
     searches from the beginning of the file until a login name matching
     name is found, and returns a pointer to the particular structure in
     which it was found. If an end-of-file 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. endpwent() may be called to close the pass-
     word file when processing is complete.




Page 1                       Reliant UNIX 5.44                Printed 11/98

getpwent(3C)                                                   getpwent(3C)

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

RESULT
     getpwent(), getpwnid(), getpwnam(), and fgetpwent() return a null
     pointer on EOF or error.

ERRORS
     The following error code descriptions are function-specific. You will
     find a general description in introprm2(2) or in errno(5).

     The getpwent(), setpwent() and endpwent() functions may fail if:

     EIO       An I/O error has occurred.

     In addition, getpwent() and setpwent() may fail if:

     EMFILE    OPENMAX file descriptors are currently open in the calling
               process.

     ENFILE    The maximum allowable number of files is currently open in
               the system.

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

     Applications wishing to check for error situations must set errno to
     zero before calling the appropriate function.

     The features of a current process can be ascertained as follows:

     getpwuid(geteuid()) returns the name associated with the effective
                         user ID of the access, getlogin() returns the name
                         associated with the current login activity, and

     getpwuid(getuid())  returns the name associated with the real user ID
                         of the process.

FILES
     /etc/passwd

SEE ALSO
     getgrent(3C), getlogin(3C), passwd(4), pwd(5).










Page 2                       Reliant UNIX 5.44                Printed 11/98