NAME

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent − get password file entry

SYNOPSIS

#include <pwd.h>

struct passwd ∗getpwent ( )

struct passwd ∗getpwuid (uid)
uid_t uid;

struct passwd ∗getpwnam (name)
char ∗name;

void setpwent ( )

void endpwent ( )

struct passwd ∗fgetpwent (f)
FILE ∗f;

DESCRIPTION

The getpwent, getpwuid, and getpwnam functions locate an entry in the /etc/passwd file, and return a pointer to an object of type struct passwd. 

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

The pw_comment field is unused; the others have meanings described in passwd(4).

Getpwent when first called returns a pointer to the first passwd structure in the file; thereafter, it returns a pointer to the next passwd structure in the file.  In this way, successive calls can be used to search the entire file.  Getpwent opens the /etc/passwd file prior to doing its work and leaves the file open afterward; setpwent has the effect of rewinding this file to allow repeated searches; endpwent can be called to close the file when processing is complete. 

Getpwuid searches from the beginning of the file 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 file until a login name matching name is found, and returns a pointer to the particular structure in which it was found. 

Fgetpwent returns a pointer to the next passwd structure in the standard I/O stream f, which should be open for reading, and its contents should match the format of /etc/passwd. 

SECURITY FEATURES

If the secure password file (/.secure/etc/passwd) exists on the system and the calling process has permission to access it, the getpwent routines fill in the encrypted password, audit ID, and audit flag from the corresponding entry in that file. 

If the secure password file exists but the caller does not have permission to read the it, the encrypted password field is set to * and the audit ID and audit flag are set to -1. 

If the secure password file does not exist, the encrypted password in /etc/passwd is returned and the audit ID and audit flag are set to -1. 

In situations where it is not necessary to get information from the regular password file, getspwent(3C) is significantly faster because it avoids unnecessary searches of the regular password file, and does not use the Yellow Pages database.

Putpwent affects only /etc/passwd; the audit ID and audit flag in the password structure are ignored.  Putspwent(3C) must be used to modify /.secure/etc/passwd. 

NETWORKING FEATURES

NFS
If an entry beginning with a plus sign (’+’) or a minus sign (’-’) is found, these routines try to use the Yellow Pages network database for data. See passwd(4) for proper syntax and operation. 

RETURN VALUE

The getpwent, getpwuid, getpwnam, and fgetpwent functions return a NULL pointer if an end-of-file or error is encountered on reading.  Otherwise, the return value points to an internal static area containing a valid passwd structure. 

WARNINGS

The above routines use <stdio.h> and the Yellow Pages library, which causes them to increase the size of programs, not otherwise using standard I/O and Yellow Pages, more than might be expected. 

The value returned by these functions 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. 

DEPENDENCIES

NFS

FILES

/etc/yp/domainname/passwd.byname
/etc/yp/domainname/passwd.byuid

SEE ALSO

ypcat(1). 

AUTHOR

Getpwent, getpwuid, getpwnam, setpwent, endpwent, and fgetpwent were developed by AT&T and HP. 

FILES

/etc/passwd

SEE ALSO

cuserid(3S), getlogin(3C), getgrent(3C), stdio(3S), passwd(4), getspwent(3C), putspwent(3C). 

ypcat(1), spasswd(4) in HP-UX Networking Reference. 

STANDARDS CONFORMANCE

getpwent: SVID2, XPG2

endpwent: SVID2, XPG2

fgetpwent: SVID2, XPG2

getpwnam: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1

getpwuid: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1

setpwent: SVID2, XPG2

Hewlett-Packard Company  —  HP-UX Release 7.0: Sept 1989