getpwent(3C) SDK R4.11 getpwent(3C)
NAME
getpwent, getpwentr, getpwuid, getpwuidr, getpwnam, getpwnamr,
setpwent, endpwent, setpwfile, fgetpwent, fgetpwentr - manipulate
password file entry
SYNOPSIS
#include <pwd.h>
struct passwd *getpwent(void);
struct passwd *getpwentr(struct passwd *result, char *buffer,
int buflen);
struct passwd *getpwuid(uidt uid);
struct passwd *getpwuidr(uidt uid, struct passwd *result,
char *buffer, int buflen);
struct passwd *getpwnam(const char *name);
struct passwd *getpwnamr(const char *name,
struct passwd *result, char *buffer, int buflen);
setpwent(void);
endpwent(void);
setpwfile(char *name);
struct passwd *fgetpwent(FILE *f);
struct passwd *fgetpwentr(FILE *f, struct passwd *result,
char *buffer, int buflen);
DESCRIPTION
getpwent, getpwentr, getpwuid, getpwuidr, getpwnam, and getpwnamr
each return a pointer to an object with the following structure
containing the broken-out fields of a line in the password stream.
The password stream consists of the /etc/passwd file and optionally
the Network Information Services (NIS) password database.
struct passwd {
char *pwname; /* The login name of the user. */
char *pwpasswd; /* The encrypted password (if any). */
uidt pwuid; /* The numerical user id. */
gidt pwgid; /* The numerical group id. */
char *pwage; /* Denotes the algorithm for when */
/* the password has expired and must be changed. */
char *pwcomment; /* A field of optional string data. */
char *pwgecos; /* A field of optional string data. */
char *pwdir; /* The initial working directory. */
char *pwshell; /* The user's initial login program.*/
};
The pwcomment and pwgecos fields are not used.
setpwent opens the database; endpwent closes it. getpwuid,
getpwuidr, getpwnam, and getpwnamr search the database (opening it
if necessary) for a matching uid or name. EOF is returned if there
is no entry.
For programs wishing to read the entire database, getpwent and
getpwentr read the next line (opening the database if necessary).
In addition to opening the database, setpwent can be used to make
getpwent getpwentr begin their search from the beginning of the
database.
setpwfile changes the default password file to name thus allowing
alternate password files to be used. Note that it does not close the
previous file. If this is desired, endpwent should be called prior
to it.
fgetpwent and fgetpwentr return a pointer to the next passwd
structure in the stream f, which matches the format of the password
file /etc/passwd.
The functions getpwentr, getpwuidr, getpwnamr, and fgetpwentr
differ from their non r counterparts by the addition of three
arguments. When calling these, the passwd structure pointed to by
result will be updated. In addition, a pointer to a buffer and
buflen (the length of the buffer) must be passed. These new
arguments are used to rid the r functions' dependencies on static
data.
Considerations for Threads Programming
+------------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+------------+-----------------------------+
|endpwent | Y N N |
|fgetpwent | N - - |
|fgetpwentr | Y N N |
|getpwent | N - - |
|getpwentr | Y N N |
|getpwuid | N - - |
|getpwuidr | Y Y N |
|getpwnam | N - - |
|getpwnamr | Y Y N |
|setpwent | Y N N |
|setpwfile | Y N N |
+------------+-----------------------------+
When the getpwentr, getpwuidr, getpwnamr, and fgetpwentr
functions are used in a threaded application, they share the same
state information (position in file, etc.) so they can work
cooperatively. In other words, if a number of threads are repeatedly
calling the getpwentr function, each routine call will pick up where
the other left off so successive calls in all threads may be used to
search the entire file.
FILES
/etc/passwd
DIAGNOSTICS
The routines getpwent, getpwuid, getpwnam, and fgetpwent, return a
null pointer (0) on EOF or error.
If the functions getpwentr, getpwuidr, getpwnamr, and fgetpwentr
are called with a value of buflen that is too small for the operation
to be performed, the function will return a NULL and errno will be
set to ERANGE.
NOTES
The functions getpwentr, getpwuidr, getpwnamr, and fgetpwentr are
only available in the shared library libc.so.
The functions getpwentr and fgetpwentr are only visible when the
DGUXTHREADSEXTENSIONS macro is defined during compilation (cc
-DDGUXTHREADSEXTENSIONS). This is because these functions are not
part of the 1003.4a Draft.
SEE ALSO
ypserv(1M), reentrant(3), getlogin(3C), getgrent(3C), passwd(4).
BUGS
In all of the above functions except getpwentr, getpwuidr,
getpwnamr, and fgetpwentr, the information is contained in a static
area, so it must be copied if it is to be saved.
STANDARDS
When using m88kbcs as the Software Development Environment target,
the functions mentioned above will be implemented on top of the
bcscat command. Because of this, some performance degradation may
be noticed in comparison to using these routines in /lib/libc.a.
Licensed material--property of copyright holder(s)