1GETPWENT(3) Library Functions Manual GETPWENT(3)
2
6 getpwent, getpwnam, getpwuid, setpassent, setpwfile, setpwent, endpwent
7 - get password file entries
8
10 #include <sys/types.h>
11 #include <pwd.h>
12 struct passwd *getpwent()
14 struct passwd *getpwnam(login)
16 char *login;
17 struct passwd *getpwuid(uid)
19 uid_t uid;
20 int setpassent(stayopen)
22 int stayopen;
23 void setpwfile(file)
25 char *file;
26 int setpwent()
28 void endpwent()
30
32 Getpwent, getpwuid, and getpwnam each return a pointer to a structure
33 containing the broken-out fields of a line in the password file. This
34 structure is defined by the include file <pwd.h>, and contains the fol‐
35 lowing fields:
36 struct passwd {
38 char *pw_name; /* user name */
39 char *pw_passwd; /* encrypted password */
40 uid_t pw_uid; /* user uid */
41 gid_t pw_gid; /* user gid */
42 time_t pw_change; /* password change time */
43 char *pw_class; /* user access class */
44 char *pw_gecos; /* Honeywell login info */
45 char *pw_dir; /* home directory */
46 char *pw_shell; /* default shell */
47 time_t pw_expire; /* account expiration */
48 };
49 These fields are more completely described in passwd(5).
51 Getpwnam and getpwuid search the password database for a matching user
53 name or user uid, respectively, returning the first one encountered.
54 Identical user names or user uids may result in undefined behavior.
55 Getpwent sequentially reads the password database and is intended for
57 programs that wish to step through the complete list of users.
58 All three routines will open the password file for reading, if neces‐
60 sary.
61 Setpwfile changes the default password file to file, thus allowing the
63 use of alternate password files.
64 Setpassent opens the file or rewinds it if it is already open. If
66 stayopen is non-zero, file descriptors are left open, significantly
67 speeding up subsequent calls. This functionality is unnecessary for
68 getpwent as it doesn't close its file descriptors by default. It
69 should also be noted that it is dangerous for long-running programs to
70 use this functionality as the password file may be updated by
71 chpass(1), passwd(1), or vipw(8).
72 Setpwent is identical to setpassent with an argument of zero.
74 Endpwent closes any open files.
76 These routines have been written to ``shadow'' the password file, e.g.
78 allow only certain programs to have access to the encrypted password.
79 This is done by using the mkpasswd(8) program, which creates ndbm(3)
80 databases that correspond to the password file, with the single excep‐
81 tion that, rather than storing the encrypted password in the database,
82 it stores the offset in the password file where the encrypted password
83 may be found. Getpwent, getpwnam, and getpwuid will use the ndbm files
84 in preference to the ``real'' password files, only reading the password
85 file itself, to obtain the encrypted password, if the process is run‐
86 ning with an effective user id equivalent to super-user. If the pass‐
87 word file itself is protected, and the ndbm files are not, this makes
88 the password available only to programs running with super-user privi‐
89 leges.
90
92 /etc/passwd
93
95 getlogin(3), getgrent(3), ndbm(3), passwd(5)
96
98 The routines getpwent, getpwnam, and getpwuid, return a null pointer on
99 EOF or error. Setpassent and setpwent return 0 on failure and 1 on
100 success. Endpwent and setpwfile have no return value.
101
103 All information is contained in a static buffer which is overwritten by
104 each new call. It must be copied elsewhere to be retained.
105 Intermixing calls to getpwent with calls to getpwnam or getpwuid, or
107 intermixing calls to getpwnam and getpwuid, after using setpassent to
108 require that file descriptors be left open, may result in undefined
109 behavior.
110 The routines getpwent, endpwent, setpassent, and setpwent are fairly
112 useless in a networked environment and should be avoided, if possible.
1137th Edition February 23, 1989 GETPWENT(3)