# getpwent

## NAME



           getpwent, setpwent, endpwent - get password file entry
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <sys/types.h>**
           **#include <pwd.h>**
    
           **struct passwd *getpwent(void);**
           **void setpwent(void);**
           **void endpwent(void);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **getpwent**(), **setpwent**(), **endpwent**():
               _XOPEN_SOURCE >= 500
                   || /* glibc >= 2.19: */ _DEFAULT_SOURCE
                   || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
    


## DESCRIPTION



           The **getpwent**() function returns a pointer to a structure
           containing the broken-out fields of a record from the password
           database (e.g., the local password file _/etc/passwd_ , NIS, and
           LDAP).  The first time **getpwent**() is called, it returns the first
           entry; thereafter, it returns successive entries.
    
           The **setpwent**() function rewinds to the beginning of the password
           database.
    
           The **endpwent**() function is used to close the password database
           after all processing has been performed.
    
           The _passwd_ structure is defined in _< pwd.h>_ as follows:
    
               struct passwd {
                   char   *pw_name;       /* username */
                   char   *pw_passwd;     /* user password */
                   uid_t   pw_uid;        /* user ID */
                   gid_t   pw_gid;        /* group ID */
                   char   *pw_gecos;      /* user information */
                   char   *pw_dir;        /* home directory */
                   char   *pw_shell;      /* shell program */
               };
    
           For more information about the fields of this structure, see
           passwd(5).
    


## RETURN VALUE



           The **getpwent**() function returns a pointer to a _passwd_ structure,
           or NULL if there are no more entries or an error occurred.  If an
           error occurs, _errno_ is set to indicate the error.  If one wants to
           check _errno_ after the call, it should be set to zero before the
           call.
    
           The return value may point to a static area, and may be
           overwritten by subsequent calls to **getpwent**(), getpwnam(3), or
           getpwuid(3).  (Do not pass the returned pointer to free(3).)
    


## ERRORS



           **EINTR** A signal was caught; see signal(7).
    
           **EIO** I/O error.
    
           **EMFILE** The per-process limit on the number of open file
                  descriptors has been reached.
    
           **ENFILE** The system-wide limit on the total number of open files has
                  been reached.
    
           **ENOMEM** Insufficient memory to allocate _passwd_ structure.
    
           **ERANGE** Insufficient buffer space supplied.
    


## FILES



           _/etc/passwd_
                  local password database file
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌─────────────┬───────────────┬──────────────────────────────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **getpwent**()  │ Thread safety │ MT-Unsafe race:pwent             │
           │             │               │ race:pwentbuf locale             │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **setpwent**(), │ Thread safety │ MT-Unsafe race:pwent locale      │
           │ **endpwent**()  │               │                                  │
           └─────────────┴───────────────┴──────────────────────────────────┘
    
           In the above table, _pwent_ in _race:pwent_ signifies that if any of
           the functions **setpwent**(), **getpwent**(), or **endpwent**() are used in
           parallel in different threads of a program, then data races could
           occur.
    


## VERSIONS



           The _pw_gecos_ field is not specified in POSIX, but is present on
           most implementations.
    


## STANDARDS



           POSIX.1-2008.
    


* * *