NAME

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

SYNOPSIS

#include <pwd.h>

struct passwd ∗getpwent ( );

struct passwd ∗getpwuid (uid)
int uid;

struct passwd ∗getpwnam (name)
char ∗name;

void setpwent ( );

void endpwent ( );

DESCRIPTION

Getpwent, getpwuid and getpwnam each returns a pointer to an object with the following structure containing the broken-out fields of a line in the /etc/passwd file.  Each line in the file contains a “passwd” structure, declared in the <pwd.h> header file:

structpasswd {
char∗pw_name;
char∗pw_passwd;
intpw_uid;
intpw_gid;
char∗pw_age;
char∗pw_comment;
char∗pw_gecos;
char∗pw_dir;
char∗pw_shell;
};

structcomment {
char∗c_dept;
char∗c_name;
char∗c_acct;
char∗c_bin;
};

This structure is declared in <pwd.h> so it is not necessary to redeclare it.

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; 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. 

FILES

/etc/passwd

SEE ALSO

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

DIAGNOSTICS

A NULL pointer is returned on EOF or error. 

WARNING

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

BUGS

All information is contained in a static area, so it must be copied if it is to be saved.  Also see cuserid(3S).

NOTE

There are two versions of the primitives documented in this manual entry:  a vanilla version and a Yellow Pages version.  The programmatic interface of both versions is identical.  The vanilla version gets its information from an ASCII file in /etc. The Yellow Pages version knows about Sun’s Yellow Pages distributed lookup service. If you want the Yellow Pages version, link the program according to the instructions for (3Y) primitives as described in intro(3). Refer to ypserv(1M) and the NFS User’s Guide for more information about the Yellow Pages. 

Version 3.6  —  December 20, 1987