GETPWENT(3C) GETPWENT(3C)
getpwent, getpwent_r, getpwuid, getpwuid_r, getpwnam, getpwnam_r,
setpwent, endpwent, fgetpwent, fgetpwent_r - get password file entry
#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;
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 backend
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;
};
Page 1
GETPWENT(3C) GETPWENT(3C)
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.
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.
Page 2
GETPWENT(3C) GETPWENT(3C)
For getpwnam and getpwuid only, if the file /etc/shadow is present, and
the current effective user ID is root, 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.
/etc/passwd /var/ns/cache/passwd.byname.m /var/ns/cache/passwd.byuid.m
nsd(1M), getlogin(3C), getgrent(3C), getspent(3C), passwd(4), shadow(4)
fopen(3S).
A NULL pointer is returned on EOF or error.
All of the functions use fopen(3S) and are thus subject to its
limitations.
PPPPaaaaggggeeee 3333 [ Back ]
|
