setpwent(3C)
NAME
getpwnam, getpwnam_r, getpwent, getpwent_r, getpwuid,
getpwuid_r, setpwent, endpwent, fgetpwent, fgetpwent_r - get
password entry
SYNOPSIS
#include <pwd.h>
struct passwd *getpwnam(const char *name);
struct passwd *getpwnam_r(const char *name, struct passwd
*pwd, char *buffer, int buflen);
struct passwd *getpwent(void);
struct passwd *getpwent_r(struct passwd *pwd, char *buffer,
int buflen);
struct passwd *getpwuid(uid_t uid);
struct passwd *getpwuid_r(uid_t uid, struct passwd *pwd,
char *buffer, int buflen);
void setpwent(void);
void endpwent(void);
struct passwd *fgetpwent(FILE *f);
struct passwd *fgetpwent_r(FILE *f, struct passwd *pwd, char
*buffer, int buflen);
POSIX
cc [ flag...] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
int getpwnam_r(const char *name, struct passwd *pwd, char
*buffer, size_t bufsize, struct passwd **result);
int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer,
size_t bufsize, struct passwd **result);
DESCRIPTION
These functions are used to obtain password entries. Entries
can come from any of the sources for passwd specified in the
/etc/nsswitch.conf file (see nsswitch.conf(4)).
The getpwnam() function searches for a password entry with
the login name specified by the character string parameter
name.
The getpwuid() function searches for a password entry with
the (numeric) user ID specified by the parameter uid.
The setpwent(), getpwent(), and endpwent() functions are
used to enumerate password entries from the database.
setpwent() sets (or resets) the enumeration to the beginning
of the set of password entries. This function should be
called before the first call to getpwent(). Calls to
getpwnam() and getpwuid() leave the enumeration position in
an indeterminate state. Successive calls to getpwent()
return either successive entries or NULL, indicating the end
of the enumeration.
The endpwent() function may be called to indicate that the
caller expects to do no further password retrieval opera-
tions; the system may then close the password file, deallo-
cate resources it was using, and so forth. It is still
allowed, but possibly less efficient, for the process to
call more password functions after calling endpwent().
The fgetpwent() function, unlike the other functions above,
does not use nsswitch.conf; it reads and parses the next
line from the stream f, which is assumed to have the format
of the passwd file. See passwd(4).
Reentrant Interfaces
The functions getpwnam(), getpwuid(), getpwent(), and
fgetpwent() use static storage that is reused in each call,
making these routines unsafe for use in multithreaded appli-
cations.
The parallel functions getpwnam_r(), getpwuid_r(),
getpwent_r(), and fgetpwent_r() provide reentrant interfaces
for these operations.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the "_r" suf-
fix. The reentrant interfaces, however, use buffers sup-
plied by the caller to store returned results, and are safe
for use in both single-threaded and multithreaded applica-
tions.
Each reentrant interface takes the same parameters as its
non-reentrant counterpart, as well as the following addi-
tional parameters. The parameter pwd must be a pointer to a
struct passwd structure allocated by the caller. On suc-
cessful completion, the function returns the password entry
in this structure. The parameter buffer is a pointer to a
buffer supplied by the caller, used as storage space for the
password data. All of the pointers within the returned
struct passwd pwd point to data stored within this buffer;
see RETURN VALUES. The buffer must be large enough to hold
all the data associated with the password entry. The param-
eter buflen (or bufsize for the POSIX versions; see stan-
dards(5)) should give the size in bytes of buffer. The POSIX
versions place a pointer to the modified pwd structure in
the result parameter, instead of returning a pointer to this
structure.
For enumeration in multithreaded applications, the position
within the enumeration is a process-wide property shared by
all threads. The setpwent() function may be used in a mul-
tithreaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to
getpwent_r(), the threads will enumerate disjoint subsets of
the password database.
Like their non-reentrant counterparts, getpwnam_r() and
getpwuid_r() leave the enumeration position in an indeter-
minate state.
RETURN VALUES
Password entries are represented by the struct passwd struc-
ture defined in <pwd.h>:
struct passwd {
char *pw_name; /* user's login name */
char *pw_passwd; /* no longer used */
uid_t pw_uid; /* user's uid */
gid_t pw_gid; /* user's gid */
char *pw_age; /* not used */
char *pw_comment; /* not used */
char *pw_gecos; /* typically user's full name */
char *pw_dir; /* user's home dir */
char *pw_shell; /* user's login shell */
};
The pw_passwd member should not be used as the encrypted
password for the user; use getspnam() or getspnam_r()
instead. See getspnam(3C).
The getpwnam(), getpwnam_r(), getpwuid(), and getpwuid_r()
functions each return a pointer to a struct passwd if they
successfully locate the requested entry; otherwise they
return NULL. Upon successful completion (including the case
when the requested entry is not found), the POSIX functions
getpwnam_r() and getpwuid_r() return 0. Otherwise, an error
number is returned to indicate the error.
The getpwent(), getpwent_r(), fgetpwent(), and fgetpwent_r()
functions each return a pointer to a struct passwd if they
successfully enumerate an entry; otherwise they return NULL,
indicating the end of the enumeration.
The getpwnam(), getpwuid(), getpwent(), and fgetpwent()
functions use static storage, so returned data must be
copied before a subsequent call to any of these functions if
the data is to be saved.
When the pointer returned by the reentrant functions
getpwnam_r(), getpwuid_r(), getpwent_r(), and fgetpwent_r()
is non-null, it is always equal to the pwd pointer that was
supplied by the caller.
ERRORS
The reentrant functions getpwnam_r(), getpwuid_r(),
getpwent_r(), and fgetpwent_r() will return NULL and set
errno to ERANGE (or in the case of POSIX functions
getpwnam_r() and getpwuid_r() return the ERANGE error) if
the length of the buffer supplied by caller is not large
enough to store the result. See Intro(2) for the proper
usage and interpretation of errno in multithreaded applica-
tions.
USAGE
Applications that use the interfaces described on this
manual page cannot be linked statically, since the implemen-
tations of these functions employ dynamic loading and link-
ing of shared objects at run time.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| ____________________________|_____________________________|_
| MT-Level | See "Reentrant Interfaces"|
| | in DESCRIPTION. |
|_____________________________|_____________________________|
SEE ALSO
nispasswd(1), passwd(1), yppasswd(1), Intro(2), Intro(3),
cuserid(3C), getgrnam(3C), getlogin(3C), getspnam(3C),
nsswitch.conf(4), passwd(4), shadow(4), attributes(5), stan-
dards(5)
NOTES
When compiling multithreaded programs, see Intro(3), Notes
On Multithreaded Applications.
Use of the enumeration interfaces getpwent() and
getpwent_r() is discouraged; enumeration is supported for
the passwd file, NIS, and NIS+, but in general is not effi-
cient and may not be supported for all database sources.
The semantics of enumeration are discussed further in
nsswitch.conf(4).
Previous releases allowed the use of `+' and `-' entries in
/etc/passwd to selectively include and exclude NIS entries.
The primary usage of these `+/-' entries is superseded by
the name service switch, so the `+/-' form may not be sup-
ported in future releases.
If required, the `+/-' functionality can still be obtained
for NIS by specifying compat as the source for passwd.
If the `+/-' functionality is required in conjunction with
NIS+, specify both compat as the source for passwd and
nisplus as the source for the pseudo-database passwd_compat.
See passwd(4), shadow(4), and nsswitch.conf(4) for details.
If the `+/-' is used, both /etc/shadow and /etc/passwd
should have the same `+' and `-' entries to ensure con-
sistency between the password and shadow databases.
If a password entry from any of the sources contains an
empty uid or gid field, that entry will be ignored by the
files, NIS , and NIS+ name service switch backends. This
will cause the user to appear unknown to the system.
If a password entry contains an empty gecos, home directory,
or shell field, getpwnam() and getpwnam_r() return a pointer
to a null string in the respective field of the passwd
structure.
If the shell field is empty, login(1) automatically assigns
the default shell. See login(1).
Solaris 2.4 and earlier releases provided definitions of the
getpwnam_r() and getpwuid_r() functions as specified in
POSIX.1c Draft 6. The final POSIX.1c standard changed the
interface for these functions. Support for the Draft 6
interface is provided for compatibility only and may not be
supported in future releases. New applications and libraries
should use the POSIX standard interface.
For POSIX.1c-compliant applications, the
_POSIX_PTHREAD_SEMANTICS and _REENTRANT flags are automati-
cally turned on by defining the _POSIX_C_SOURCE flag with a
value >= 199506L.
Man(1) output converted with
man2html