GETPWENT(3,L)               AIX Technical Reference               GETPWENT(3,L)



-------------------------------------------------------------------------------
getpwent, getpwuid, getpwnam, setpwent, endpwent



PURPOSE

Gets a password file entry.

LIBRARY

Standard C Library (libc.a)

SYNTAX

#include <pwd.h>



      struct passwd *getpwent ( )         void setpwent ( )

      struct passwd *getpwuid (uid)       void endpwent ( )
      int uid;

      struct passwd *getpwnam (name)
      char *name;



DESCRIPTION

The getpwent, getpwuid, and getpwnam subroutines return a pointer to a
structure containing the broken-out fields of a line in the /etc/passwd file.
The passwd structure is defined in the pwd.h header file, and it contains the
following members:

      char  *pw_name;
      char  *pw_passwd;
      uid_t pw_uid;
      gid_t pw_gid;
      char  *pw_age;
      int   pw_quota;
      char  *pw_comment;
      char  *pw_etc;
      char  *pw_dir;
      char  *pw_shell;

The fields have meanings described in "passwd."

The getpwent subroutine, when first called, returns a pointer to the first
passwd structure in the file.  On the next call, it returns a pointer to the




Processed November 7, 1990       GETPWENT(3,L)                                1

GETPWENT(3,L)               AIX Technical Reference               GETPWENT(3,L)



next passwd structure in the file. Successive calls can be used to search the
entire file.

The getpwuid subroutine searches from the beginning of the file until it finds
a numerical user ID matching the uid parameter.  The subroutine then returns a
pointer to the structure in which it was found.

The getpwnam subroutine searches from the beginning of the file until it finds
a login name matching the name parameter.  The search is made using flattened
names; the characters of the name searched for are the ASCII equivalent
character (see "Introduction to International Character Support" in Managing
the AIX Operating System.)  The subroutine then returns a pointer to the
structure in which it was found.

If an end-of-file condition or an error is encountered on reading, these
functions return a NULL pointer.

The setpwent subroutine rewinds the password file to allow repeated searches.

The endpwent subroutine closes the group file when processing is complete.

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

FILE

/etc/passwd

ERROR CONDITIONS

The getpwuid and getpwnam subroutines fail if one or more of the following are
true:

EIO       An I/O error has occurred.

EINTR     A signal was caught during the function.

EMFILE    Too many file descriptors are currently open for the process.

ENFILE    The system file table is full.

RELATED INFORMATION

In this book:  "getgrent, getgrgid, getgrnam, setgrent, endgrent," "getlogin,"
and "putpwent."

"Introduction to International Character Support" in Managing the AIX Operating
System.







Processed November 7, 1990       GETPWENT(3,L)                                2