getpwent()

Get the next entry from the password database

Synopsis:

#include <sys/types.h>
#include <pwd.h>

struct passwd* getpwent( void );

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The getpwent() function returns the next entry from the password database. This function uses a static buffer that's overwritten by each call.

Note: The getpwent(), getpwnam(), and getpwuid(), functions share the same static buffer. For a reentrant version of this function, see getpwent_r().

When getpwent() is first called, the password database is opened, and remains open until either a NULL is returned to signify end-of-file, or endpwent() is called.

Returns:

A pointer to an object of type struct passwd containing the next entry from the password database. When getpwent() reaches the end of the database, it returns NULL but doesn't change the value of errno; on error, it returns NULL and sets errno.

Errors:

The getpwent() function uses the following functions, and as a result, errno can be set to an error for any of these calls:

Examples:

/*
 * This program loops, reading a login name from standard
 * input and checking to see if it is a valid name. If it 
 * is not valid, the entire contents of the name in the 
 * password database are printed.
 */
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <pwd.h>

int main( void )
  {
    struct passwd* pw;
    char    buf[80];

    setpwent( );
    while( gets( buf ) != NULL ) {
      if( ( pw = getpwnam( buf ) ) != ( struct passwd * )0 ) {
        printf( "Valid login name is: %s\n", pw->pw_name );
      } else {
        setpwent( );
        while( ( pw=getpwent( ) ) != ( struct passwd * )0 )
          printf( "%s\n", pw->pw_name );
      }
    }
    endpwent();
    return( EXIT_SUCCESS );
  }

Classification:

POSIX 1003.1

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler No
Thread No