|HP-UX Reference > G
HP-UX 11i Version 3: February 2007
getpwent(), getpwuid(), getpwuid_r(), getpwnam(), getpwnam_r(), setpwent(), endpwent(), fgetpwent() — get password file entry
#include <pwd.h> struct passwd *getpwent(void); struct passwd *getpwuid(uid_t uid); int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer, size_t buflen, struct passwd **result); struct passwd *getpwnam(const char *name); int getpwnam_r(char *name, struct passwd *pwd, char *buffer, size_t buflen, struct passwd **result); void setpwent(void); void endpwent(void); struct passwd *fgetpwent(FILE *stream);
getpwent(), getpwuid(), and getpwnam() are used to obtain password entries, and return a pointer to an object of passwd structure. An entry may come from any of the sources for passwd specified in the /etc/nsswitch.conf file. See nsswitch.conf(4).
The passwd structure is defined in <pwd.h> and includes the following members:
char *pw_name; /* user name */ char *pw_passwd; /* encrypted password */ uid_t pw_uid; /* user id */ gid_t pw_gid; /* group id */ char *pw_age; /* password aging */ char *pw_comment; /* unused */ char *pw_gecos; /* user fullname, office, extension, homephone*/ char *pw_dir; /* initial directory */ char *pw_shell; /* initial shell */ aid_t pw_audid; /* numerical audit id */ int pw_audflg; /* numerical audit flag */
The pw_comment field is unused. For more information on the other fields, see the passwd(4) manpage.
getpwent_r(), setpwent_r(), endpwent_r(), fgetpwent_r() get password file entry.
getpwuid_r(), and getpwnam_r() both update the struct passwd pointed to by pwd and store a pointer to that structure at the location pointed to by result. The structure must contain an entry from the user database with a matching uid or name. Storage referenced by the passwd structure pointed to by pwd is allocated from the memory provided with the buffer parameter, which is defined as buflen in size. The maximum size needed for this buffer can be determined with the _SC_GETPW_R_SIZE_MAX sysconf() parameter. A NULL pointer is returned at the location pointed to by result on error or if the requested entry is not found.
When the repository is set to files in the /etc/nsswitch.conf file, then the getpwent(), getpwuid(), getpwuid_r(), getpwnam(), and getpwnam_r() calls return the passwd structure exactly as it appears in the /etc/passwd file. In shadowed standard mode, the calls normally return "x" (instead of the encrypted password and aging information) in the pw_passwd field. The same applies for calls to fgetpwent() when the argument stream is set to /etc/passwd.
If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default * that is in /etc/passwd and the audit ID and audit flag will be set to -1. On trusted systems, if it is not necessary to obtain information from the regular password file, /etc/passwd, users should use getprpwent() to access the protected password database. See getprpwent(3) and getspwent(3X).
putpwent() affects only /etc/passwd, and the audit ID and audit flag in the password structure are ignored. putprpwnam() must be used to modify the protected password database entries. See getprpwent(3).
See WARNINGS about trusted system support.
getpwent(), getpwuid(), getpwnam(), and fgetpwent() return a NULL pointer if an end-of-file or error is encountered on reading. fgetpwent() returns a NULL pointer on encountering an invalid entry. An invalid entry is one which does not follow the /etc/passwd structure. Otherwise, the return value points to an internal static area containing a valid passwd structure.
getpwuid_r() and getpwnam_r() return zero upon success. Otherwise, an error number is returned to indicate the error.
getpwent(), getpwuid(), getpwnam(), and fgetpwent() fail if any of the following are true:
The getpwnam_r() and getpwuid_r() functions will fail if:
The value returned by getpwent(), getpwuid(), getpwnam(), and fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved.
The following fields have numerical limitations as noted:
Users of getpwuid_r() and getpwnam_r() should note that these interfaces now conform with POSIX.1c. getpwent_r(), setpwent_r(), endpwent_r() and fgetpwent_r() are obsolescent interfaces. These interfaces and the old prototypes of getpwuid_r() and getpwnam_r() are supported for compatibility with existing DCE applications only.
The interfaces getpwuid(), getpwnam(), getpwent(), setpwent(), endpwent(), fgetpwent(), getpwuid_r() and getpwnam_r() use the Dynamic Name Service Switch. See nsswitch.conf(4). An application that uses these interfaces cannot be fully archive bound.
HP-UX 11i Version 3 is the last release to support trusted systems functionality.
The following code excerpt prints name and uid of a user logged in on this terminal:
struct passwd pwd; struct passwd *result; char logBuffer ; char pwdBuffer ; if (getlogin_r (loginBuffer, 1024) == 0) if (getpwnam_r (logBuffer, &pwd, pwdBuffer, 1024, &result) == 0) printf ("Name = %s; uid = %d\n", pwd.pw_name, pwd.pw_uid);
getpwent(), getpwuid(), getpwnam(), setpwent(), endpwent(), and fgetpwent() were developed by Sun and HP.