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 operations; the system may then close the password file, deallocate 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

Password entries are represented by the struct passwd structure 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.

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 applications.

Applications that use the interfaces described on this manual page cannot be linked statically, since the implementations of these functions employ dynamic loading and linking of shared objects at run time.

See attributes(5) for descriptions of the following attributes:

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), standards(5)

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 efficient 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 supported 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 consistency 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 automatically turned on by defining the _POSIX_C_SOURCE flag with a value >= 199506L.