getpwent(3C)

NAME

getpwent(), getpwuid(), getpwuid_r(), getpwnam(), getpwnam_r(), setpwent(), endpwent(), fgetpwent() — get password file entry

SYNOPSIS

#include <pwd.h> 

struct passwd *getpwent(void); 

struct passwd *getpwuid(uid_t uid); 

int  getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer, 
     size_t buflen, struct passwd **result); 

struct passwd *getpwnam(const char *name); 

int  getpwnam_r(char *name, struct passwd *pwd, char *buffer, 
     size_t buflen, struct passwd **result); 

void setpwent(void); 

void endpwent(void); 

struct passwd *fgetpwent(FILE *stream);

Obsolescent Interfaces

#include <pwd.h> 

int  getpwent_r(struct passwd *result, char *buffer, int buflen, 
     FILE **pwfp); 

void setpwent_r(FILE **pwfp); 

void endpwent_r(FILE **pwfp); 

int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, 
     int buflen); 

DESCRIPTION

getpwent(), getpwuid(), and getpwnam() are used to obtain password entries, and return a pointer to an object of passwd structure. An entry may come from any of the sources for passwd specified in the /etc/nsswitch.conf file. See nsswitch.conf(4).

The passwd structure is defined in <pwd.h> and includes the following members:

char    *pw_name;     /* user name */ 
char    *pw_passwd;   /* encrypted password */ 
uid_t   pw_uid;       /* user id */ 
gid_t   pw_gid;       /* group id */ 
char    *pw_age;      /* password aging */ 
char    *pw_comment;  /* unused */ 
char    *pw_gecos;    /* user fullname, office, extension, homephone*/ 
char    *pw_dir;      /* initial directory */ 
char    *pw_shell;    /* initial shell */ 
aid_t   pw_audid;     /* numerical audit id */ 
int     pw_audflg;    /* numerical audit flag */ 

The pw_comment field is unused. For more information on the other fields, see the passwd(4) manpage.

getpwent(): When first called, getpwent() returns a pointer to the first passwd structure in the password database. Thereafter, it returns a pointer to the next passwd structure in the database.
setpwent(): Has the effect of rewinding the password database to allow repeated searches.
endpwent(): Can be called to indicate that password database processing is complete.
getpwuid(): Searches from the beginning of the password database until a numeric user ID matching uid is found, and returns a pointer to the particular structure in which it was found.
getpwnam(): Searches from the beginning of the password database until a login name matching name is found, and returns a pointer to the particular structure in which it was found.
fgetpwent(): Unlike the other functions above, does not use nsswitch.conf, nor access NIS It returns a pointer to the next passwd structure in the standard I/O stream stream, which should be open for reading, and its contents should match the format of /etc/passwd.

Obsolescent Interfaces

getpwent_r(), setpwent_r(), endpwent_r(), fgetpwent_r() get password file entry.

Reentrant Interfaces

getpwuid_r(), and getpwnam_r() both update the struct passwd pointed to by pwd and store a pointer to that structure at the location pointed to by result. The structure must contain an entry from the user database with a matching uid or name. Storage referenced by the passwd structure pointed to by pwd is allocated from the memory provided with the buffer parameter, which is defined as buflen in size. The maximum size needed for this buffer can be determined with the _SC_GETPW_R_SIZE_MAX sysconf() parameter. A NULL pointer is returned at the location pointed to by result on error or if the requested entry is not found.

Notes

When the repository is set to files in the /etc/nsswitch.conf file, then the getpwent(), getpwuid(), getpwuid_r(), getpwnam(), and getpwnam_r() calls return the passwd structure exactly as it appears in the /etc/passwd file. In shadowed standard mode, the calls normally return "x" (instead of the encrypted password and aging information) in the pw_passwd field. The same applies for calls to fgetpwent() when the argument stream is set to /etc/passwd.

SECURITY FEATURES

If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default * that is in /etc/passwd and the audit ID and audit flag will be set to -1. On trusted systems, if it is not necessary to obtain information from the regular password file, /etc/passwd, users should use getprpwent() to access the protected password database. See getprpwent(3) and getspwent(3X).

putpwent() affects only /etc/passwd, and the audit ID and audit flag in the password structure are ignored. putprpwnam() must be used to modify the protected password database entries. See getprpwent(3).

See WARNINGS about trusted system support.

RETURN VALUE

getpwent(), getpwuid(), getpwnam(), and fgetpwent() return a NULL pointer if an end-of-file or error is encountered on reading. fgetpwent() returns a NULL pointer on encountering an invalid entry. An invalid entry is one which does not follow the /etc/passwd structure. Otherwise, the return value points to an internal static area containing a valid passwd structure.

getpwuid_r() and getpwnam_r() return zero upon success. Otherwise, an error number is returned to indicate the error.

ERRORS

getpwent(), getpwuid(), getpwnam(), and fgetpwent() fail if any of the following are true:

EIO: An I/O error has occurred.
EMFILE: OPEN_MAX descriptors are currently open in the calling process.
ENFILE: The maximum allowable number of files is currently open in the system.

The getpwnam_r() and getpwuid_r() functions will fail if:

ERANGE: Insufficient storage was supplied via buffer and bufsize to contain the data to be referenced by the resulting passwd structure

WARNINGS

The value returned by getpwent(), getpwuid(), getpwnam(), and fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved.

The following fields have numerical limitations as noted:

The user ID is an integer value between -2 and UID_MAX inclusive.
The group ID is an integer value between 0 and UID_MAX inclusive.

Users of getpwuid_r() and getpwnam_r() should note that these interfaces now conform with POSIX.1c. getpwent_r(), setpwent_r(), endpwent_r() and fgetpwent_r() are obsolescent interfaces. These interfaces and the old prototypes of getpwuid_r() and getpwnam_r() are supported for compatibility with existing DCE applications only.

The interfaces getpwuid(), getpwnam(), getpwent(), setpwent(), endpwent(), fgetpwent(), getpwuid_r() and getpwnam_r() use the Dynamic Name Service Switch. See nsswitch.conf(4). An application that uses these interfaces cannot be fully archive bound.

HP-UX 11i Version 3 is the last release to support trusted systems functionality.

EXAMPLE

The following code excerpt prints name and uid of a user logged in on this terminal:

struct passwd pwd; 
struct passwd *result; 
char logBuffer [1024]; 
char pwdBuffer [1024]; 
  
if (getlogin_r (loginBuffer, 1024) == 0) 
  if (getpwnam_r (logBuffer, &pwd, pwdBuffer, 1024, &result) == 0) 
    printf ("Name = %s; uid = %d\n", pwd.pw_name, pwd.pw_uid); 

DEPENDENCIES

NFS

Files

/var/yp/domainname/passwd.byname
/var/yp/domainname/passwd.byuid
/var/nis/hostname/passwd.org_dir

AUTHOR

getpwent(), getpwuid(), getpwnam(), setpwent(), endpwent(), and fgetpwent() were developed by Sun and HP.

FILES

/etc/passwd: System Password file

STANDARDS CONFORMANCE

getpwent(): SVID2, SVID3, XPG2

endpwent(): SVID2, SVID3, XPG2

fgetpwent(): SVID2, SVID3, XPG2

getpwnam(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

getpwuid(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

setpwent(): SVID2, SVID3, XPG2

getpwent(3C)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Obsolescent Interfaces

DESCRIPTION

Obsolescent Interfaces

Reentrant Interfaces

Notes

SECURITY FEATURES

RETURN VALUE

ERRORS

WARNINGS

EXAMPLE

DEPENDENCIES

NFS

Files

AUTHOR

FILES

SEE ALSO

STANDARDS CONFORMANCE