# endpwent

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           endpwent, getpwent, setpwent — user database functions
    


## SYNOPSIS



           #include <pwd.h>
    
           void endpwent(void);
           struct passwd *getpwent(void);
           void setpwent(void);
    


## DESCRIPTION



           These functions shall retrieve information about users.
    
           The _getpwent_() function shall return a pointer to a structure
           containing the broken-out fields of an entry in the user database.
           Each entry in the user database contains a **passwd** structure. If
           the user database is not already open, _getpwent_() shall open it
           and return a pointer to a **passwd** structure containing the first
           entry in the database. Thereafter, it shall return 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.
    
           If an end-of-file or an error is encountered on reading,
           _getpwent_() shall return a null pointer.
    
           An implementation that provides extended security controls may
           impose further implementation-defined restrictions on accessing
           the user database. In particular, the system may deny the
           existence of some or all of the user database entries associated
           with users other than the caller.
    
           The _setpwent_() function shall rewind the user database so that the
           next _getpwent_() call returns the first entry, allowing repeated
           searches.
    
           The _endpwent_() function shall close the user database.
    
           The _setpwent_() and _endpwent_() functions shall not change the
           setting of _errno_ if successful.
    
           On error, the _setpwent_() and _endpwent_() functions shall set _errno_
           to indicate the error.
    
           Since no value is returned by the _setpwent_() and _endpwent_()
           functions, an application wishing to check for error situations
           should set _errno_ to 0, then call the function, then check _errno_.
    
           These functions need not be thread-safe.
    


## RETURN VALUE



           On successful completion, _getpwent_() shall return a pointer to a
           **passwd** structure. On end-of-file, _getpwent_() shall return a null
           pointer and shall not change the setting of _errno_.  On error,
           _getpwent_() shall return a null pointer and _errno_ shall be set to
           indicate the error.
    
           The application shall not modify the structure to which the return
           value points, nor any storage areas pointed to by pointers within
           the structure. The returned pointer, and pointers within the
           structure, might be invalidated or the structure or the storage
           areas might be overwritten by a subsequent call to _getpwuid_(),
           _getpwnam_(), or _getpwent_().  The returned pointer, and pointers
           within the structure, might also be invalidated if the calling
           thread is terminated.
    


## ERRORS



           These functions may fail if:
    
           **EINTR** A signal was caught during the operation.
    
           **EIO** An I/O error has occurred.
    
           In addition, _getpwent_() and _setpwent_() may fail if:
    
           **EMFILE** All file descriptors available to the process are currently
                  open.
    
           **ENFILE** The maximum allowable number of files is currently open in
                  the system.
    
           _The following sections are informative._
    


## EXAMPLES



       **Searching the User Database**
           The following example uses the _getpwent_() function to get
           successive entries in the user database, returning a pointer to a
           **passwd** structure that contains information about each user. The
           call to _endpwent_() closes the user database and cleans up.
    
               #include <pwd.h>
               #include <stdio.h>
    
               void printname(uid_t uid)
               {
                   struct passwd *pwd;
    
                   setpwent();
                   while((pwd = getpwent()) != NULL) {
                       if (pwd->pw_uid == uid) {
                           printf("name=%s\n",pwd->pw_name);
                           break;
                       }
                   }
                   endpwent();
               }
    


## APPLICATION USAGE



           These functions are provided due to their historical usage.
           Applications should avoid dependencies on fields in the password
           database, whether the database is a single file, or where in the
           file system name space the database resides. Applications should
           use _getpwuid_() whenever possible because it avoids these
           dependencies.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *