Commit | Line | Data |
---|---|---|
d1455a8c KB |
1 | .\" Copyright (c) 1988 The Regents of the University of California. |
2 | .\" All rights reserved. | |
62ab31a2 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
d1455a8c | 5 | .\" |
91cff1e1 | 6 | .\" @(#)getpwent.3 6.6 (Berkeley) %G% |
4e6e003a | 7 | .\" |
3fb9eae6 | 8 | .TH GETPWENT 3 "" |
4e6e003a KM |
9 | .AT 3 |
10 | .SH NAME | |
d1455a8c KB |
11 | getpwent, getpwnam, getpwuid, setpassent, |
12 | setpwfile, setpwent, endpwent \- get password file entries | |
4e6e003a KM |
13 | .SH SYNOPSIS |
14 | .nf | |
d1455a8c | 15 | .B #include <sys/types.h> |
4e6e003a KM |
16 | .B #include <pwd.h> |
17 | .PP | |
d1455a8c KB |
18 | .B struct passwd *getpwent() |
19 | .PP | |
20 | .B struct passwd *getpwnam(login) | |
21 | .B char *login; | |
22 | .PP | |
4e6e003a | 23 | .B struct passwd *getpwuid(uid) |
62ab31a2 | 24 | .B uid_t uid; |
4e6e003a | 25 | .PP |
d1455a8c KB |
26 | .B int setpassent(stayopen) |
27 | .B int stayopen; | |
4e6e003a | 28 | .PP |
d1455a8c KB |
29 | .B void setpwfile(file) |
30 | .B char *file; | |
1e00f4a7 | 31 | .PP |
d1455a8c | 32 | .B int setpwent() |
4e6e003a | 33 | .PP |
62ab31a2 | 34 | .B void endpwent() |
4e6e003a KM |
35 | .fi |
36 | .SH DESCRIPTION | |
d1455a8c KB |
37 | .IR Getpwent , |
38 | .IR getpwuid , | |
4e6e003a KM |
39 | and |
40 | .I getpwnam | |
d1455a8c KB |
41 | each return a pointer to a structure containing the broken-out |
42 | fields of a line in the password file. This structure is defined | |
43 | by the include file | |
44 | .IR < pwd.h > , | |
45 | and contains the following fields: | |
4e6e003a | 46 | .PP |
d1455a8c | 47 | .RS |
4e6e003a | 48 | .nf |
62ab31a2 | 49 | struct passwd { |
d1455a8c KB |
50 | char *pw_name; /* user name */ |
51 | char *pw_passwd; /* encrypted password */ | |
52 | uid_t pw_uid; /* user uid */ | |
53 | gid_t pw_gid; /* user gid */ | |
54 | time_t pw_change; /* password change time */ | |
55 | char *pw_class; /* user access class */ | |
56 | char *pw_gecos; /* Honeywell login info */ | |
57 | char *pw_dir; /* home directory */ | |
58 | char *pw_shell; /* default shell */ | |
59 | time_t pw_expire; /* account expiration */ | |
62ab31a2 | 60 | }; |
4e6e003a KM |
61 | .fi |
62 | .RE | |
63 | .PP | |
d1455a8c | 64 | These fields are more completely described in |
4e6e003a KM |
65 | .IR passwd (5). |
66 | .PP | |
d1455a8c KB |
67 | .I Getpwnam |
68 | and | |
69 | .I getpwuid | |
70 | search the password database for a matching user name or user uid, | |
71 | respectively, returning the first one encountered. Identical | |
72 | user names or user uids may result in undefined behavior. | |
73 | .PP | |
74 | .I Getpwent | |
75 | sequentially reads the password database and is intended for programs | |
76 | that wish to step through the complete list of users. | |
77 | .PP | |
78 | All three routines will open the password file for reading, if | |
79 | necessary. | |
80 | .PP | |
62ab31a2 KB |
81 | .I Setpwfile |
82 | changes the default password file to | |
d1455a8c KB |
83 | .IR file , |
84 | thus allowing the use of alternate password files. | |
85 | .PP | |
86 | .I Setpassent | |
87 | opens the file or rewinds it if it is already open. If | |
88 | .I stayopen | |
89 | is non-zero, file descriptors are left open, significantly speeding | |
90 | up subsequent calls. This functionality is unnecessary for | |
91 | .I getpwent | |
92 | as it doesn't close its file descriptors by default. It should also | |
93 | be noted that it is dangerous for long-running programs to use this | |
94 | functionality as the password file may be updated by | |
95 | .IR chpass (1), | |
96 | .IR passwd (1), | |
97 | or | |
98 | .IR vipw (8). | |
62ab31a2 | 99 | .PP |
1e00f4a7 | 100 | .I Setpwent |
d1455a8c KB |
101 | is identical to |
102 | .I setpassent | |
103 | with an argument of zero. | |
62ab31a2 KB |
104 | .PP |
105 | .I Endpwent | |
d1455a8c | 106 | closes any open files. |
62ab31a2 | 107 | .PP |
d1455a8c KB |
108 | These routines have been written to ``shadow'' the password file, e.g. |
109 | allow only certain programs to have access to the encrypted password. | |
110 | This is done by using the | |
111 | .IR mkpasswd (8) | |
112 | program, which creates | |
113 | .IR ndbm (3) | |
114 | databases that correspond to the password file, with the single exception | |
115 | that, rather than storing the encrypted password in the database, it stores | |
116 | the offset in the password file where the encrypted password may be found. | |
117 | .IR Getpwent , | |
118 | .IR getpwnam , | |
1e00f4a7 | 119 | and |
d1455a8c KB |
120 | .I getpwuid |
121 | will use the | |
122 | .I ndbm | |
123 | files in preference to the ``real'' password files, only reading the | |
124 | password file itself, to obtain the encrypted password, if the process | |
125 | is running with an effective user id equivalent to super-user. | |
126 | If the password file itself is protected, and the | |
127 | .I ndbm | |
128 | files are not, this makes the password available only to programs | |
129 | running with super-user privileges. | |
4e6e003a KM |
130 | .SH FILES |
131 | /etc/passwd | |
132 | .SH "SEE ALSO" | |
d1455a8c | 133 | getlogin(3), getgrent(3), ndbm(3), passwd(5) |
4e6e003a | 134 | .SH DIAGNOSTICS |
c5892565 KM |
135 | The routines |
136 | .IR getpwent , | |
d1455a8c KB |
137 | .IR getpwnam , |
138 | and | |
c5892565 | 139 | .IR getpwuid , |
d1455a8c KB |
140 | return a null pointer on EOF or error. |
141 | .I Setpassent | |
c5892565 | 142 | and |
d1455a8c KB |
143 | .I setpwent |
144 | return 0 on failure and 1 on success. | |
62ab31a2 KB |
145 | .I Endpwent |
146 | and | |
147 | .I setpwfile | |
148 | have no return value. | |
4e6e003a | 149 | .SH BUGS |
d1455a8c KB |
150 | All information is contained in a static buffer which is overwritten |
151 | by each new call. It must be copied elsewhere to be retained. | |
152 | .PP | |
153 | Intermixing calls to | |
154 | .IR getpwent | |
155 | with calls to | |
156 | .I getpwnam | |
157 | or | |
158 | .IR getpwuid , | |
159 | or intermixing calls to | |
160 | .I getpwnam | |
161 | and | |
162 | .IR getpwuid , | |
163 | after using | |
164 | .I setpassent | |
165 | to require that file descriptors be left open, may result | |
166 | in undefined behavior. | |
167 | .PP | |
168 | The routines | |
169 | .IR getpwent , | |
170 | .IR endpwent , | |
171 | .IR setpassent , | |
172 | and | |
173 | .IR setpwent | |
174 | are fairly useless in a networked environment and should be | |
175 | avoided, if possible. |