./_Man_SunOS_4.1.3_html/html3/getpwent.3v.html

Manual page for GETPWENT(3V)

getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile, 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()

int setpwfile(name)
char *name;

struct passwd *fgetpwent(f)
FILE *f;

DESCRIPTION

getpwent(), getpwuid() and getpwnam() each return a pointer to an object with the following structure containing the fields of a line in the password file. Each line in the file contains a passwd structure, declared in the <pwd.h> header file:

struct	passwd {
	char	*pw_name;
	char	*pw_passwd;
	uid_t	pw_uid;
	gid_t	pw_gid;
	int	pw_quota;
	char	*pw_comment;
	char	*pw_gecos;
	char	*pw_dir;
	char	*pw_shell;
};
struct passwd *getpwent(), *getpwuid(), *getpwnam();

The fields pw_quota and pw_comment are unused; the others have meanings described in passwd.5 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; so successive calls can be used to search the entire file. getpwuid() searches from the beginning of the file until a numerical 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. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer.

A call to setpwent() has the effect of rewinding the password file to allow repeated searches. endpwent() may be called to close the password file when processing is complete.

setpwfile() changes the default password file to name thus allowing alternate password files to be used. Note: it does not close the previous file. If this is desired, endpwent() should be called prior to it. setpwfile() will fail if it is called before a call to one of getpwent(), getpwuid(), setpwent(), or getpwnam() , or if it is called before a call to one of these functions and after a call to endpwent().

fgetpwent() returns a pointer to the next passwd structure in the stream f, which matches the format of the password file /etc/passwd.

SYSTEM V DESCRIPTION

struct passwd is declared in pwd.h as:

struct	passwd {
	char	*pw_name;
	char	*pw_passwd;
	uid_t	pw_uid;
	gid_t	pw_gid;
	char	*pw_age;
	char	*pw_comment;
	char	*pw_gecos;
	char	*pw_dir;
	char	*pw_shell;
};

The field pw_age is used to hold a value for ``password aging'' on some systems; ``password aging'' is not supported on Sun systems.

RETURN VALUES

getpwent(), getpwuid(), and getpwnam() return a pointer to struct passwd on success. On EOF or error, or if the requested entry is not found, they return NULL.

setpwfile() returns:

1: on success.
0: on failure.

FILES

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

NOTES

The above routines use the standard I/O library, which increases the size of programs not otherwise using standard I/O more than might be expected.

setpwfile() and fgetpwent() are obsolete and should not be used, because when the system is running in secure mode (see issecure.3 the password file only contains part of the information needed for a user database entry.

BUGS

All information is contained in a static area which is overwritten by subsequent calls to these functions, so it must be copied if it is to be saved.