GETPWENT(3C) GETPWENT(3C) NAME getpwent, getpwent_r, getpwuid, getpwuid_r, getpwnam, getpwnam_r, setpwent, endpwent, fgetpwent, fgetpwent_r - get password file entry SYNOPSIS #include <pwd.h> struct passwd *getpwent(void); struct passwd *getpwent_r(struct passwd *pwent, char *buffer, size_t bufsize); struct passwd *getpwuid(uid_t uid); int getpwuid_r(uid_t uid, struct passwd *pwent, char *buffer, size_t bufsize, struct passwd **result); struct passwd *getpwnam(const char *name); int getpwnam_r(const char *name, struct passwd *pwent, char *buffer, size_t bufsize, struct passwd **result); void setpwent(void); void endpwent(void); struct passwd *fgetpwent(FILE *f); struct passwd *fgetpwent_r(FILE *f, struct passwd *pwent, char *buffer, size_t bufsize); extern int _getpwent_no_yp; extern int _getpwent_no_shadow; extern int _pw_stayopen; DESCRIPTION getpwent, getpwuid , getpwnam and their reentrant counterparts each return a pointer to an object with the following structure containing the broken-out fields of a line in the /etc/passwd file or some other back- end database. 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; char *pw_age; char *pw_comment; char *pw_gecos; char *pw_dir; char *pw_shell; }; This structure is declared in <pwd.h> so it is not necessary to redeclare it. The fields 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. The getpwnam_r and getpwuid_r calls are reentrant versions of the getpwnam and getpwuid calls. The extra arguments are pwent, buffer are used for internal storage, bufsize is the size of buffer, and result is the struct passwd used to return the requested information. A good size of buffer is BUFSIZ bytes. 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. fgetpwent returns a pointer to the next passwd structure in the stream f, which matches the format of /etc/passwd. The routines getpwent, fgetpwent, getpwnam and getpwuid all return data from a statically allocated space which is overwritten on each call. Reentrant versions of these routines getpwent_r, fgetpwent_r, getpwnam_r, and getpwuid_r are provided which will parse the result into supplied space. Each takes three extra arguments, a pointer to a struct passwd structure, a pointer to a character buffer, and a length for the buffer. NOTES In IRIX 4.0, there were two versions of the getpwent primitives: the standard version in libc and the NIS version in libsun. The routines in this release only parse files in the format given in passwd(4). Either the static file /etc/passwd or a dynamic file supplied by the nsd(1M) daemon. The nsd daemon can supply data from any number of back-end databases or protocols as controlled by the nsd configuration file /etc/nsswitch.conf. To force these routines to use only the static file set the external variable _getpwent_no_yp to 1. This is only really useful for programs that will use this information in subsequent putpwent(3C) calls (otherwise, the entire back-end database will be copied to /etc/passwd). _getpwent_no_yp is understood by getpwent, getpwnam, getpwuid and their reentrant counterparts. For getpwnam and getpwuid only, if the file /etc/shadow is present and is readable by the user, the password entry will be copied out of /etc/shadow and placed in the pw_passwd field. This compatibility feature permits programs expecting password information to be in /etc/passwd to function properly in a shadow password environment. Note that the aging information from /etc/shadow is not made available in pw_age. For portability to other systems, the existence of /etc/shadow should be dealt with by the program, not this interface (see getspent(3C)). To disable this behavior (for example, to make a verbatim copy of /etc/passwd using putpwent(3C)), set the external variable _getpwent_no_shadow to 1. To cause the password file to be left open until an explicit call to endpwent(3C), set the external variable _pw_stayopen to 1. By default, _getpwent_no_yp, _getpwent_no_shadow, and _pw_stayopen are 0. The Mips ABI specifies nothing but local files so applications which wish to use anything else must compile with libc prior to libnsl in the library list. When nsd is running changes to the local passwd file may not be noticed by getpwent() until the enumeration cache file has timed out. FILES /etc/passwd /var/ns/cache/passwd.byname.m /var/ns/cache/passwd.byuid.m SEE ALSO nsd(1M), getlogin(3C), getgrent(3C), getspent(3C), passwd(4), shadow(4) fopen(3S). DIAGNOSTICS A NULL pointer is returned on EOF or error. BUGS All of the functions use fopen(3S) and are thus subject to its limitations. Page 3