getpwnam(3C)

NAME

getpwnam, getpwent, getpwuid, setpwent, endpwent, fgetpwent − get password entry

SYNOPSIS

#include <pwd.h>

struct passwd ∗getpwnam(const char ∗name);

struct passwd ∗getpwent(void);

struct passwd ∗getpwuid(uid_t uid);

void setpwent(void);

void endpwent(void);

struct passwd ∗fgetpwent(FILE ∗f);

DESCRIPTION

getpwent(), getpwuid(), and getpwnam() each return a password entry. The entry may come from one of the following sources: the passwd file (see passwd(4)), the NIS maps “passwd.byname” and "passwd.byuid", and the NIS+ table “passwd”. The sources and their lookup order are specified in the /etc/nsswitch.conf file (see nsswitch.conf(4)).

getpwnam() searches for a password entry with a given login name.

getpwuid() searches for a password entry with a given (numeric) user id.

getpwent() enumerates password entries: successive calls to getpwent() will return either successive password entries or NULL. Enumeration may not be supported by some sources.

setpwent() “rewinds” to the beginning of the enumeration of password entries. Calls to getpwnam() and getpwuid() may leave the enumeration in an indeterminate state, so setpwent() should be called before the first getpwent().

endpwent() may be called to indicate that password processing is complete; the system may then close any open password file, deallocate storage, and so forth. It is legitimate, but possibly less efficient, to call more password routines after endpwent().

fgetpwent(), unlike the routines 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 passwd(4).

The internal representation of a password entry is a passwd structure defined in <pwd.h> with the following entries:

char∗pw_name;
char∗pw_passwd;
uid_tpw_uid;
gid_tpw_gid;
char∗pw_age;
char∗pw_comment;
char∗pw_gecos;
char∗pw_dir;
char∗pw_shell;

RETURN VALUES

getpwnam() and getpwuid() return a pointer to a struct passwd if they successfully locate the requested entry; otherwise they return NULL.

getpwent() and fgetpwent() return a pointer to a struct passwd if they successfully enumerate an entry; otherwise they return NULL, indicating the end of the enumeration.

FILES

/etc/passwd, /etc/shadow, /etc/nsswitch.conf

NOTES

All information is contained in a static area, so it must be copied if it is to be saved.

The pw_passwd field in the passwd structure should not be used as the encrypted password for the user, use getspnam() instead. getspnam() and getspent() always use the same sources and lookup order as do getpwnam(), getpwuid(), and getpwent().

Previous releases used “+” and “-” entries in /etc/passwd to selectively include and exclude entries from NIS . If still required, this is supported by a “compat” source; as a consequence, both /etc/shadow and /etc/passwd should have the same "+" and “-” entries to ensure consistency between the password and shadow routines. If compatibility with the +/- syntax is desired in conjunction with NIS+, this is supported by using the “nisplus” source for the pseudo-database passwd_compat.

The “compat” source may not be supported in future releases. The preferred sources are “files” and “nisplus”; they obviate the use of “+” and “-” entries in /etc/passwd and /etc/shadow. See passwd(4), shadow(4) and nsswitch.conf(4) for details.

Use of getpwent() is deprecated; enumeration is well-defined for the passwd file and is supported (albeit inefficiently) for NIS and NIS+, but in general may not be well-defined. The semantics of enumeration are discussed in nsswitch.conf(4).

BUGS

Programs that call getpwnam() or getpwuid() routines cannot be linked statically since the implementation of these routines requires dynamic linker functionality to access shared objects at run time.

SunOS 5.1/SPARC — Last change: 24 Feb 1992

Museum

Related Articles