getpwent(S-osr5)

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

Syntax

cc . . . -lc

#include <pwd.h>

struct passwd *getpwent ()

struct passwd *getpwuid (uid)
uid_t uid;

struct passwd *getpwnam (name)
const char *name;

void setpwent ()

void endpwent ()

struct passwd *fgetpwent (f)
FILE *f;

Description

The getpwent, getpwuid, and getpwnam routines each returns a pointer to an object with a structure containing the broken-out fields of a line in the /etc/passwd file, a passwd structure declared in the <pwd.h> header file. Refer to this header file for a listing of the passwd structure. Because the elements vary by the type of standards compliance that you are using, it is not included here. Because this structure is in <pwd.h>, it does not need to be redeclared. The meanings of the fields in the passwd structure are described in passwd(FP).

When the getpwent routine is first called, it returns a pointer to the first passwd structure in the /etc/passwd file. Thereafter, it returns a pointer to the next passwd structure in the file. So successive calls to getpwent can be used to search the entire file.

The getpwuid routine searches from the beginning of the /etc/passwd file until a numerical user ID matching the argument uid is found. getpwuid returns a pointer to the particular passwd structure in which the argument uid was found.

Like getpwuid, the getpwnam routine searches from the beginning of the /etc/passwd file until a login name matching the argument name is found. getpwnam returns a pointer to the particular passwd structure in which the argument name was found.

The setpwent routine resets the file pointer to the beginning of the password file, /etc/passwd, to allow repeated searches. The endpwent routine closes the password file, /etc/passwd, when processing is complete.

The fgetpwent routine returns a pointer to the next passwd structure which matches the format of /etc/passwd in the stream argument f.

Return value

Upon successful completion, the routines getpwent, getpwuid, getpwnam, and fgetpwent each return a pointer to a passwd structure. If an end-of-file or an error is encountered on reading, these routines return a NULL pointer. No errors are defined for the setpwent or endpwent routines.

Diagnostics

Use feof( ) to test if a null return value is caused by an end-of-file or from a syntax error in the password file. The feof macro is described on the ferror(S-osr5) manual page.

Note

All information is contained in a static area, so it must be copied if it is to be saved. Otherwise, it may be overwritten on subsequent calls to these routines.

These routines are also included in libsocket. The libsocket version provides the same functionality described here, in addition to providing the NIS support. Link with libsocket using cc ... -lsocket to get the additional NIS (Network Information Service) functionality.

Files

/etc/passwd

Standards conformance

endpwent, getpwent and setpwent is not part of any currently supported standard; it was developed by UNIX System Laboratories, Inc. and is maintained by The SCO Group.

getpwnam and getpwuid conforms with:

X/Open Portability Guide, Issue 3, 1989 ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .

The fgetpwent routine has been withdrawn from XPG3.