getpwent(3C) DG/UX 5.4R3.00 getpwent(3C)
NAME
getpwent, getpwent_r, getpwuid, getpwuid_r, getpwnam, getpwnam_r,
setpwent, endpwent, setpwfile, fgetpwent, fgetpwent_r - manipulate
password file entry
SYNOPSIS
#include <pwd.h>
struct passwd *getpwent(void);
struct passwd *getpwent_r(struct passwd *result, char *buffer,
int buflen);
struct passwd *getpwuid(uid_t uid);
struct passwd *getpwuid_r(uid_t uid, struct passwd *result,
char *buffer, int buflen);
struct passwd *getpwnam(const char *name);
struct passwd *getpwnam_r(const char *name,
struct passwd *result, char *buffer, int buflen);
setpwent(void);
endpwent(void);
setpwfile(char *name);
struct passwd *fgetpwent(FILE *f);
struct passwd *fgetpwent_r(FILE *f, struct passwd *result,
char *buffer, int buflen);
DESCRIPTION
getpwent, getpwent_r, getpwuid, getpwuid_r, getpwnam, and getpwnam_r
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 *pw_name; /* The login name of the user. */
char *pw_passwd; /* The encrypted password (if any). */
uid_t pw_uid; /* The numerical user id. */
gid_t pw_gid; /* The numerical group id. */
char *pw_age; /* Denotes the algorithm for when */
/* the password has expired and must be changed. */
char *pw_comment; /* A field of optional string data. */
char *pw_gecos; /* A field of optional string data. */
char *pw_dir; /* The initial working directory. */
char *pw_shell; /* The user's initial login program.*/
};
Licensed material--property of copyright holder(s) 1
getpwent(3C) DG/UX 5.4R3.00 getpwent(3C)
The pw_comment and pw_gecos fields are not used.
setpwent opens the database; endpwent closes it. getpwuid,
getpwuid_r, getpwnam, and getpwnam_r 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
getpwent_r read the next line (opening the database if necessary).
In addition to opening the database, setpwent can be used to make
getpwent getpwent_r 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 fgetpwent_r return a pointer to the next passwd
structure in the stream f, which matches the format of the password
file /etc/passwd.
The functions getpwent_r, getpwuid_r, getpwnam_r, and fgetpwent_r
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 - - |
|fgetpwent_r | Y N N |
|getpwent | N - - |
|getpwent_r | Y N N |
|getpwuid | N - - |
|getpwuid_r | Y Y N |
|getpwnam | N - - |
|getpwnam_r | Y Y N |
|setpwent | Y N N |
|setpwfile | Y N N |
+------------+-----------------------------+
When the getpwent_r, getpwuid_r, getpwnam_r, and fgetpwent_r
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 getpwent_r function, each routine call will pick up where
the other left off so successive calls in all threads may be used to
Licensed material--property of copyright holder(s) 2
getpwent(3C) DG/UX 5.4R3.00 getpwent(3C)
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 getpwent_r, getpwuid_r, getpwnam_r, and fgetpwent_r
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 getpwent_r, getpwuid_r, getpwnam_r, and fgetpwent_r are
only available in the shared library libc.so.
The functions getpwent_r and fgetpwent_r are only visible when the
_DGUX_THREADS_EXTENSIONS macro is defined during compilation (cc
-D_DGUX_THREADS_EXTENSIONS). 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 getpwent_r, getpwuid_r,
getpwnam_r, and fgetpwent_r, 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
bcs_cat 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) 3