getpwent(3C)

NAME

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

SYNOPSIS

#include <pwd.h>

struct passwd *getpwent(void);

struct passwd *getpwuid(uid_t uid);

struct passwd *getpwnam(const char *name);

void setpwent(void);

void endpwent(void);

struct passwd *fgetpwent(FILE *stream);

DESCRIPTION

getpwent(), getpwuid(), and getpwnam() 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:

char    *pw_name;
char    *pw_passwd;
int     pw_uid;
int     pw_gid;
char    *pw_age;
char    *pw_comment;
char    *pw_gecos;
char    *pw_dir;
char    *pw_shell;
long    pw_audid;
int     pw_audflg;

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

getpwent() When first called, getpwent() 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 stream, 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 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() is significantly faster because it avoids unnecessary searches of the regular password file (see getspwent(3C)), and does not use the Network Information Service database.

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

NETWORKING FEATURES

NFS

If an entry beginning with a plus sign (+) or a minus sign (−) is found, these routines try to use the Network Information Service network database for data. See passwd(4) for proper syntax and operation.

RETURN VALUE

getpwent(), getpwuid(), getpwnam(), and fgetpwent() 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 Network Information Service library, which causes them to increase the size of programs, not otherwise using standard I/O and Network Information Service, 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.

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.

If either of these values are out of range, the getpwent(3C) functions will reset the associated ID value to (UID_MAX+1).

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

STANDARDS CONFORMANCE

getpwent(): SVID2, XPG2
endpwent(): SVID2, XPG2

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

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

Hewlett-Packard Company — HP-UX Release 9.10: April 1995

Museum

Related Articles