GETPWENT(3) UNIX Programmer's Manual GETPWENT(3) NAME getpwent, getpwnam, getpwuid, setpassent, setpwfile, setpwent, endpwent - get password file entries SYNOPSIS #include #include struct passwd *getpwent() struct passwd *getpwnam(login) char *login; struct passwd *getpwuid(uid) uid_t uid; int setpassent(stayopen) int stayopen; void setpwfile(file) char *file; int setpwent() void endpwent() DESCRIPTION _G_e_t_p_w_e_n_t, _g_e_t_p_w_u_i_d, and _g_e_t_p_w_n_a_m each return a pointer to a structure containing the broken-out fields of a line in the password file. This structure is defined by the include file , and contains the following fields: struct passwd { char *pw_name; /* user name */ char *pw_passwd; /* encrypted password */ uid_t pw_uid; /* user uid */ gid_t pw_gid; /* user gid */ time_t pw_change; /* password change time */ char *pw_class; /* user access class */ char *pw_gecos; /* Honeywell login info */ char *pw_dir; /* home directory */ char *pw_shell; /* default shell */ time_t pw_expire; /* account expiration */ }; These fields are more completely described in _p_a_s_s_w_d(5). _G_e_t_p_w_n_a_m and _g_e_t_p_w_u_i_d search the password database for a matching user name or user uid, respectively, returning the first one encountered. Identical user names or user uids may result in undefined behavior. Printed 11/26/99 February 23, 1989 1 GETPWENT(3) UNIX Programmer's Manual GETPWENT(3) _G_e_t_p_w_e_n_t sequentially reads the password database and is intended for programs that wish to step through the complete list of users. All three routines will open the password file for reading, if necessary. _S_e_t_p_w_f_i_l_e changes the default password file to _f_i_l_e, thus allowing the use of alternate password files. _S_e_t_p_a_s_s_e_n_t opens the file or rewinds it if it is already open. If _s_t_a_y_o_p_e_n is non-zero, file descriptors are left open, significantly speeding up subsequent calls. This functionality is unnecessary for _g_e_t_p_w_e_n_t as it doesn't close its file descriptors by default. It should also be noted that it is dangerous for long-running programs to use this functionality as the password file may be updated by _c_h_p_a_s_s(1), _p_a_s_s_w_d(1), or _v_i_p_w(8). _S_e_t_p_w_e_n_t is identical to _s_e_t_p_a_s_s_e_n_t with an argument of zero. _E_n_d_p_w_e_n_t closes any open files. These routines have been written to ``shadow'' the password file, e.g. allow only certain programs to have access to the encrypted password. This is done by using the _m_k_p_a_s_s_w_d(8) program, which creates _n_d_b_m(3) databases that correspond to the password file, with the single exception that, rather than storing the encrypted password in the database, it stores the offset in the password file where the encrypted password may be found. _G_e_t_p_w_e_n_t, _g_e_t_p_w_n_a_m, and _g_e_t_p_w_u_i_d will use the _n_d_b_m files in preference to the ``real'' password files, only reading the password file itself, to obtain the encrypted password, if the process is running with an effective user id equivalent to super-user. If the password file itself is protected, and the _n_d_b_m files are not, this makes the password available only to programs running with super-user privileges. FILES /etc/passwd SEE ALSO getlogin(3), getgrent(3), ndbm(3), passwd(5) DIAGNOSTICS The routines _g_e_t_p_w_e_n_t, _g_e_t_p_w_n_a_m, and _g_e_t_p_w_u_i_d, return a null pointer on EOF or error. _S_e_t_p_a_s_s_e_n_t and _s_e_t_p_w_e_n_t return 0 on failure and 1 on success. _E_n_d_p_w_e_n_t and _s_e_t_p_w_f_i_l_e have no return value. Printed 11/26/99 February 23, 1989 2 GETPWENT(3) UNIX Programmer's Manual GETPWENT(3) BUGS All information is contained in a static buffer which is overwritten by each new call. It must be copied elsewhere to be retained. Intermixing calls to _g_e_t_p_w_e_n_t with calls to _g_e_t_p_w_n_a_m or _g_e_t_p_w_u_i_d, or intermixing calls to _g_e_t_p_w_n_a_m and _g_e_t_p_w_u_i_d, after using _s_e_t_p_a_s_s_e_n_t to require that file descriptors be left open, may result in undefined behavior. The routines _g_e_t_p_w_e_n_t, _e_n_d_p_w_e_n_t, _s_e_t_p_a_s_s_e_n_t, and _s_e_t_p_w_e_n_t are fairly useless in a networked environment and should be avoided, if possible. Printed 11/26/99 February 23, 1989 3