GETPWENT(3C)                         SysV                         GETPWENT(3C)



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

SYNOPSIS
     #include <pwd.h>

     struct passwd *getpwent (void )

     struct passwd *getpwuid (uid)
     uid_t uid;

     int getpwuid_r (result, uid, buffer, len)
     uid_t uid;
     struct passwd *result;
     char *buffer;
     int len;

     struct passwd *getpwnam (name)
     const char *name;

     int getpwnam_r (result, name, buffer, len)
     const char *name;
     struct passwd *result;
     char *buffer;
     int len;

     void setpwent (void )

     void endpwent (void )

     void setpwfile(name)
     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
     password file, as declared in <pwd.h>:

          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;
          };

     The fields have meanings described in passwd(4).

     When first called, getpwent returns a pointer to the first line in the
     file.  Each call thereafter returns a pointer to a successive line.
     getpwuid and getpwnam search from the beginning of the file until a
     matching uid or name, respectively, is found, or until EOF is
     encountered.

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

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

     The getpwuid_r and getpwnam_r functions are the reentrant versions of the
     getpwuid and getpwnam functions, respectively.  Upon successful
     completion, the result is stored in two parts.  The struct passwd (which
     includes only pointers) is stored in result, and the strings themselves
     are stored in buffer.

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

     The above routines use <stdio.h>, which causes them to increase the size
     of programs, not otherwise using standard I/O, more than might be
     expected.

     Under Domain/OS SysV, /etc/passwd is a read-only object of the type
     "passwd," maintained by the registry server.  See rgyd(1M).  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.

DIAGNOSTICS
     A NULL pointer is returned on EOF or error.

     Upon successful completion, the getpwnam_r and getpwuid_r functions
     return a value of 0 (zero).  Otherwise, -1 is returned.

FILES
     /etc/passwd

SEE ALSO
     getlogin(3C), getgrent(3C), getorgent(3C), passwd(4), rgyd(1M).
     Domain/OS System Administration Reference.