getpwent(3C)

NAME

getpwent(), getpwent_r(), getpwuid(), getpwuid_r(), getpwnam(), getpwnam_r(), setpwent(), setpwent_r(), endpwent(), endpwent_r(), fgetpwent(), fgetpwent_r() − get password file entry

SYNOPSIS

#include <pwd.h>

struct passwd *getpwent(void);

int getpwent_r(struct passwd *result, char *buffer, int buflen,

FILE **pwfp);

struct passwd *getpwuid(uid_t uid);

int getpwuid_r(uid_t uid, struct passwd *result,

char *buffer, int buflen);

struct passwd *getpwnam(const char *name);

int getpwnam_r(char *name, struct passwd *result,

char *buffer, int buflen);

void setpwent(void);

void setpwent_r(FILE **pwfp);

void endpwent(void);

void endpwent_r(FILE **pwfp);

struct passwd *fgetpwent(FILE *stream);

int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);

DESCRIPTION

getpwent(), getpwuid(), and getpwnam() locate an entry in the /etc/passwd file, and return a pointer to an object of passwd structure.

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

char    *pw_name;   /* user name */
char    *pw_passwd; /* encrypted password */
uid_t   pw_uid;     /* user id */
gid_t   pw_gid;     /* group id */
char    *pw_age;    /* password aging */
char    *pw_comment;/* unused */
char    *pw_gecos; /* user fullname, office, extension, homephone*/
char    *pw_dir;    /* initial directory */
char    *pw_shell; /* initial shell */
aid_t   pw_audid;   /* numerical audit id */
int     pw_audflg; /* numerical audit flag */

The pw_comment field is unused; for more information on the other fields, refer to 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.

Reentrant Interfaces

getpwuid_r(), getpwnam_r() and fgetpwent_r() expect to be passed three extra parameters:

1. The address of a passwd structure where the result will be stored;

2. A buffer to store character strings (such as the password) to which fields in passwd structure will point;

3. The length of the user-supplied buffer.

In addition to the above three parameters, getpwent_r() requires a pointer to a (FILE *) variable into which is stored the result of an fopen() call on the /etc/passwd file. This is to allow threads to independently scan through the /etc/passwd file. setpwent_r() and endpwent_r() are to be used only in conjunction with getpwent_r() and take the same pointer to a (FILE *) variable as a parameter. setpwent_r() can be used to rewind or open the /etc/passwd file. endpwent_r() must be called when done to close the file and release memory associated with that instance of the opened file.

Note that the (FILE *) variable must be initialized to NULL before it is passed to getpwent_r() or setpwent_r() for the first time. Thereafter it should not be modified in any way.

A buffer length of 1024 is recommended.

SECURITY FEATURES

If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default * that is in /etc/passwd and the audit ID and audit flag will be set to −1. On trusted systems, if it is not necessary to obtain information from the regular password file, /etc/passwd, users should use getprpwent() to access the protected password database. See getprpwent(3) and getspwent(3X).

putpwent() affects only /etc/passwd; the audit ID and audit flag in the password structure are ignored. putprpwnam() must be used to modify the protected password databse entries. See getprpwent(3).

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.

Network Information Service (NIS) is not supported on trusted systems.

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.

getpwent_r(), getpwuid_r(), getpwnam_r(), and fgetpwent_r(), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned.

ERRORS

getpwent(), getpwuid(), and fgetpwent() fail if any of the following are true:

[EIO] An I/O error has occurred.

[EMFILE] OPEN_MAX descriptors are currently open in the calling process.

[ENFILE] The maximum allowable number of files is currently open in the system.

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

getpwent(), getpwuid(), getpwnam(), setpwent(), endpwent(), and fgetpwent() are unsafe in multi-thread applications. getpwent_r(), getpwuid_r(), getpwnam_r(), setpwent_r(), endpwent_r(), and fgetpwent_r() are MT-Safe and should be used instead.

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.

Users of getpwnam_r() and getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard.

EXAMPLE

The following code excerpt counts the number of entries in the /etc/passwd file:

int count = 0;
struct passwd pwbuf;
char buffer[1024];
FILE *pwf = NULL;
setpwent_r(&pwf);
while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)
count++;
endpwent_r(&pwf);

DEPENDENCIES

NFS

Files:

/var/yp/domainname/passwd.byname
/var/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 System Password file

STANDARDS CONFORMANCE

getpwent(): SVID2, SVID3, XPG2

endpwent(): SVID2, SVID3, XPG2

fgetpwent(): SVID2, SVID3, XPG2

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

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

setpwent(): SVID2, SVID3, XPG2

Hewlett-Packard Company — HP-UX Release 10.20: July 1996

Museum

Related Articles