Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1988, 1991 The Regents of the University of California. |
d1455a8c | 2 | .\" All rights reserved. |
62ab31a2 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
d1455a8c | 5 | .\" |
ae59e04c | 6 | .\" @(#)getpwent.3 6.8 (Berkeley) %G% |
4e6e003a | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt GETPWENT 3 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm getpwent , | |
13 | .Nm getpwnam , | |
14 | .Nm getpwuid , | |
15 | .Nm setpassent , | |
16 | .Nm setpwent , | |
17 | .Nm endpwent | |
18 | .Nd password database operations | |
19 | .Sh SYNOPSIS | |
20 | .Fd #include <sys/types.h> | |
21 | .Fd #include <pwd.h> | |
22 | .Ft struct passwd * | |
23 | .Fn getpwent void | |
24 | .Ft struct passwd * | |
25 | .Fn getpwnam "const char *login" | |
26 | .Ft struct passwd * | |
27 | .Fn getpwuid "uid_t uid" | |
28 | .Ft int | |
29 | .Fn setpassent "int stayopen" | |
30 | .Ft int | |
31 | .Fn setpwent void | |
32 | .Ft void | |
33 | .Fn endpwent void | |
34 | .Sh DESCRIPTION | |
35 | These functions | |
36 | operate on the password database file | |
37 | which is described | |
38 | in | |
39 | .Xr passwd 5 . | |
40 | Each entry in the database is defined by the structure | |
41 | .Ar passwd | |
42 | found in the include | |
43 | file | |
44 | .Aq Pa pwd.h : | |
45 | .Bd -literal -offset indent | |
62ab31a2 | 46 | struct passwd { |
ae59e04c CL |
47 | char *pw_name; /* user name */ |
48 | char *pw_passwd; /* encrypted password */ | |
d1455a8c KB |
49 | uid_t pw_uid; /* user uid */ |
50 | gid_t pw_gid; /* user gid */ | |
51 | time_t pw_change; /* password change time */ | |
ae59e04c CL |
52 | char *pw_class; /* user access class */ |
53 | char *pw_gecos; /* Honeywell login info */ | |
54 | char *pw_dir; /* home directory */ | |
55 | char *pw_shell; /* default shell */ | |
d1455a8c | 56 | time_t pw_expire; /* account expiration */ |
62ab31a2 | 57 | }; |
ae59e04c CL |
58 | .Ed |
59 | .Pp | |
60 | The functions | |
61 | .Fn getpwnam | |
d1455a8c | 62 | and |
ae59e04c CL |
63 | .Fn getpwuid |
64 | search the password database for the given login name or user uid, | |
babc0585 | 65 | respectively, always returning the first one encountered. |
ae59e04c CL |
66 | .Pp |
67 | The | |
68 | .Fn getpwent | |
69 | function | |
d1455a8c | 70 | sequentially reads the password database and is intended for programs |
babc0585 | 71 | that wish to process the complete list of users. |
ae59e04c CL |
72 | .Pp |
73 | The | |
74 | .Fn setpassent | |
75 | function | |
babc0585 KB |
76 | accomplishes two purposes. |
77 | First, it causes | |
ae59e04c | 78 | .Fn getpwent |
babc0585 KB |
79 | to ``rewind'' to the beginning of the database. |
80 | Additionally, if | |
ae59e04c | 81 | .Fa stayopen |
d1455a8c | 82 | is non-zero, file descriptors are left open, significantly speeding |
babc0585 KB |
83 | up subsequent accesses for all of the routines. |
84 | (This latter functionality is unnecessary for | |
ae59e04c | 85 | .Fn getpwent |
babc0585 | 86 | as it doesn't close its file descriptors by default.) |
ae59e04c | 87 | .Pp |
babc0585 KB |
88 | It is dangerous for long-running programs to keep the file descriptors |
89 | open the database will become out of date if it is updated while the | |
90 | program is running. | |
ae59e04c CL |
91 | .Pp |
92 | The | |
93 | .Fn setpwent | |
94 | function | |
d1455a8c | 95 | is identical to |
ae59e04c | 96 | .Fn setpassent |
d1455a8c | 97 | with an argument of zero. |
ae59e04c CL |
98 | .Pp |
99 | The | |
100 | .Fn endpwent | |
101 | function | |
d1455a8c | 102 | closes any open files. |
ae59e04c | 103 | .Pp |
d1455a8c KB |
104 | These routines have been written to ``shadow'' the password file, e.g. |
105 | allow only certain programs to have access to the encrypted password. | |
babc0585 KB |
106 | If the process which calls them has an effective uid of 0, the encrypted |
107 | password will be returned, otherwise, the password field of the retuned | |
ae59e04c CL |
108 | structure will point to the string |
109 | .Ql * . | |
110 | .Sh RETURN VALUES | |
111 | The functions | |
112 | .Fn getpwent , | |
113 | .Fn getpwnam , | |
d1455a8c | 114 | and |
ae59e04c CL |
115 | .Fn getpwuid , |
116 | return a valid pointer to a passwd structure on success | |
117 | and a null pointer if end-of-file is reached or an error occurs. | |
118 | The functions | |
119 | .Fn setpassent | |
c5892565 | 120 | and |
ae59e04c | 121 | .Fn setpwent |
d1455a8c | 122 | return 0 on failure and 1 on success. |
ae59e04c CL |
123 | The |
124 | .Fn endpwent | |
125 | function | |
babc0585 | 126 | has no return value. |
ae59e04c CL |
127 | .Sh FILES |
128 | .Bl -tag -width /etc/master.passwd -compact | |
129 | .It Pa /var/db/pwd.db | |
130 | The insecure password database file | |
131 | .It Pa /var/db/spwd.db | |
132 | The secure password database file | |
133 | .It Pa /etc/master.passwd | |
134 | The current password file | |
135 | .It Pa /etc/passwd | |
136 | A Version 7 format password file | |
137 | .El | |
138 | .Sh SEE ALSO | |
139 | .Xr getlogin 3 , | |
140 | .Xr getgrent 3 , | |
141 | .Xr passwd 5 , | |
142 | .Xr pwd_mkdb 8 , | |
143 | .Xr vipw 8 | |
144 | .Sh HISTORY | |
145 | The | |
146 | .Nm getpwent , | |
147 | .Nm getpwnam , | |
148 | .Nm getpwuid , | |
149 | .Nm setpwent, | |
150 | and | |
151 | .Nm endpwent | |
152 | functions appeared in | |
153 | .At v7 . | |
154 | The | |
155 | .Nm setpassent | |
156 | function appeared in | |
157 | .Bx 4.3 Reno . | |
158 | .Sh BUGS | |
159 | The functions | |
160 | .Fn getpwent , | |
161 | .Fn getpwnam , | |
162 | and | |
163 | .Fn getpwuid , | |
164 | leave their results in an internal static object and return | |
165 | a pointer to that object. Subsequent calls to | |
166 | the same function | |
167 | will modify the same object. | |
168 | .Pp | |
d1455a8c | 169 | The routines |
ae59e04c CL |
170 | .Fn getpwent , |
171 | .Fn endpwent , | |
172 | .Fn setpassent , | |
d1455a8c | 173 | and |
ae59e04c | 174 | .Fn setpwent |
d1455a8c KB |
175 | are fairly useless in a networked environment and should be |
176 | avoided, if possible. | |
ae59e04c | 177 | .Sh COMPATIBILITY |
babc0585 | 178 | The historic function |
ae59e04c | 179 | .Xr setpwfile 3 , |
babc0585 KB |
180 | which allowed the specification of alternate password databases, |
181 | has been deprecated and is no longer available. |