Accesses user entry information in the user database, returning a
    pointer to a passwd structure.

    Format

      #include  <pwd.h>

      struct passwd *getpwent  (void);

1  –  Function Variants

    The getpwent function has variants named __32_getpwent and
    __64_getpwent for use with 32-bit and 64-bit pointer sizes,
    respectively.

2  –  Description

    The getpwent function returns a pointer to a structure containing
    fields whose values are derived from an entry in the user
    database. Entries in the database are accessed sequentially by
    getpwent. When first called, getpwent returns a pointer to a
    passwd structure containing the first entry in the user database.
    Thereafter, it returns a pointer to a passwd structure containing
    the next entry in the user database. Successive calls can be used
    to search the entire user database.

    The passwd structure is defined in the <pwd.h> header file as
    follows:

    pw_name    The name of the user.
    pw_uid     The ID of the user.
    pw_gid     The group ID of the principle group of the user.
    pw_dir     The home directory of the user.
    pw_shell   The initial program for the user.

    If an end-of-file or an error is encountered on reading, getpwent
    returns a NULL pointer.

    Because getpwent accesses the user authorization file (SYSUAF)
    directly, the process must have appropriate privileges enabled or
    the function will fail.

                                  NOTES

       All information generated by the getpwent function is stored
       in a per-thread static area and is overwritten on subsequent
       calls to the function.

       Password file entries that are too long are ignored.

3  –  Return Values

    x                  Pointer to a passwd structure, if successful.
    NULL               Indicates an end-of-file or error occurred.
                       The function sets errno to one of the
                       following values:

                       o  EIO - Indicates that an I/O error occurred
                          or the user does not have appropriate
                          privileges enabled to access the user
                          authorization file (SYSUAF).

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

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