]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and |
2 | .\" Walter Harms (walter.harms@informatik.uni-oldenburg.de) | |
3 | .\" | |
38f20bb9 | 4 | .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
fea681da | 5 | .\" Distributed under GPL |
38f20bb9 | 6 | .\" %%%LICENSE_END |
fea681da | 7 | .\" |
4b8c67d9 | 8 | .TH GETSPNAM 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
9 | .SH NAME |
10 | getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, | |
11 | fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, | |
12 | lckpwdf, ulckpwdf \- get shadow password file entry | |
13 | .SH SYNOPSIS | |
14 | .nf | |
15 | /* General shadow password file API */ | |
fea681da | 16 | .B #include <shadow.h> |
68e4db0a | 17 | .PP |
fea681da | 18 | .BI "struct spwd *getspnam(const char *" name ); |
68e4db0a | 19 | .PP |
fea681da | 20 | .B struct spwd *getspent(void); |
68e4db0a | 21 | .PP |
fea681da | 22 | .B void setspent(void); |
68e4db0a | 23 | .PP |
fea681da | 24 | .B void endspent(void); |
68e4db0a | 25 | .PP |
86562954 | 26 | .BI "struct spwd *fgetspent(FILE *" stream ); |
68e4db0a | 27 | .PP |
fea681da | 28 | .BI "struct spwd *sgetspent(const char *" s ); |
68e4db0a | 29 | .PP |
86562954 | 30 | .BI "int putspent(const struct spwd *" p ", FILE *" stream ); |
68e4db0a | 31 | .PP |
fea681da | 32 | .B int lckpwdf(void); |
68e4db0a | 33 | .PP |
fea681da | 34 | .B int ulckpwdf(void); |
f90f031e | 35 | |
fea681da | 36 | /* GNU extension */ |
fea681da | 37 | .B #include <shadow.h> |
68e4db0a | 38 | .PP |
fea681da | 39 | .BI "int getspent_r(struct spwd *" spbuf , |
fea681da | 40 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
68e4db0a | 41 | .PP |
fea681da | 42 | .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , |
fea681da | 43 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
68e4db0a | 44 | .PP |
86562954 | 45 | .BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf , |
fea681da | 46 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
68e4db0a | 47 | .PP |
fea681da | 48 | .BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf , |
fea681da | 49 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); |
fea681da | 50 | .fi |
68e4db0a | 51 | .PP |
cc4615cc MK |
52 | .in -4n |
53 | Feature Test Macro Requirements for glibc (see | |
54 | .BR feature_test_macros (7)): | |
55 | .in | |
68e4db0a | 56 | .PP |
cc4615cc MK |
57 | .ad l |
58 | .BR getspent_r (), | |
59 | .BR getspnam_r (), | |
60 | .BR fgetspent_r (), | |
61 | .BR sgetspent_r (): | |
51c612fb MK |
62 | Since glibc 2.19: |
63 | _DEFAULT_SOURCE | |
64 | Glibc 2.19 and earlier: | |
65 | _BSD_SOURCE || _SVID_SOURCE | |
cc4615cc | 66 | .ad b |
fea681da MK |
67 | .SH DESCRIPTION |
68 | Long ago it was considered safe to have encrypted passwords openly | |
c13182ef MK |
69 | visible in the password file. |
70 | When computers got faster and people | |
fea681da MK |
71 | got more security-conscious, this was no longer acceptable. |
72 | Julianne Frances Haugh implemented the shadow password suite | |
73 | that keeps the encrypted passwords in | |
05461740 | 74 | the shadow password database |
c13182ef | 75 | (e.g., the local shadow password file |
fea681da | 76 | .IR /etc/shadow , |
05461740 | 77 | NIS, and LDAP), |
fea681da | 78 | readable only by root. |
dd3568a1 | 79 | .PP |
05461740 MK |
80 | The functions described below resemble those for |
81 | the traditional password database | |
82 | (e.g., see | |
83 | .BR getpwnam (3) | |
84 | and | |
85 | .BR getpwent (3)). | |
bea08fec | 86 | .\" FIXME . I've commented out the following for the |
c13182ef MK |
87 | .\" moment. The relationship between PAM and nsswitch.conf needs |
88 | .\" to be clearly documented in one place, which is pointed to by | |
89 | .\" the pages for the user, group, and shadow password functions. | |
777f5a9e | 90 | .\" (Jul 2005, mtk) |
c13182ef MK |
91 | .\" |
92 | .\" This shadow password setup has been superseded by PAM | |
05461740 MK |
93 | .\" (pluggable authentication modules), and the file |
94 | .\" .I /etc/nsswitch.conf | |
95 | .\" now describes the sources to be used. | |
dd3568a1 | 96 | .PP |
fea681da | 97 | The |
63aa9df0 | 98 | .BR getspnam () |
fea681da | 99 | function returns a pointer to a structure containing |
05461740 | 100 | the broken-out fields of the record in the shadow password database |
18701562 | 101 | that matches the username |
fea681da | 102 | .IR name . |
dd3568a1 | 103 | .PP |
fea681da | 104 | The |
63aa9df0 | 105 | .BR getspent () |
05461740 MK |
106 | function returns a pointer to the next entry in the shadow password |
107 | database. | |
fea681da | 108 | The position in the input stream is initialized by |
63aa9df0 | 109 | .BR setspent (). |
fea681da | 110 | When done reading, the program may call |
63aa9df0 | 111 | .BR endspent () |
fea681da MK |
112 | so that resources can be deallocated. |
113 | .\" some systems require a call of setspent() before the first getspent() | |
114 | .\" glibc does not | |
dd3568a1 | 115 | .PP |
fea681da | 116 | The |
63aa9df0 | 117 | .BR fgetspent () |
fea681da | 118 | function is similar to |
63aa9df0 | 119 | .BR getspent () |
fea681da | 120 | but uses the supplied stream instead of the one implicitly opened by |
63aa9df0 | 121 | .BR setspent (). |
dd3568a1 | 122 | .PP |
fea681da | 123 | The |
63aa9df0 | 124 | .BR sgetspent () |
fea681da MK |
125 | function parses the supplied string |
126 | .I s | |
05461740 MK |
127 | into a struct |
128 | .IR spwd . | |
dd3568a1 | 129 | .PP |
fea681da | 130 | The |
63aa9df0 | 131 | .BR putspent () |
05461740 MK |
132 | function writes the contents of the supplied struct |
133 | .I spwd | |
bd9b2a9c | 134 | .I *p |
0a3d50c6 | 135 | as a text line in the shadow password file format to |
86562954 | 136 | .IR stream . |
fea681da MK |
137 | String entries with value NULL and numerical entries with value \-1 |
138 | are written as an empty string. | |
dd3568a1 | 139 | .PP |
fea681da | 140 | The |
63aa9df0 | 141 | .BR lckpwdf () |
c13182ef | 142 | function is intended to protect against multiple simultaneous accesses |
05461740 MK |
143 | of the shadow password database. |
144 | It tries to acquire a lock, and returns 0 on success, | |
145 | or \-1 on failure (lock not obtained within 15 seconds). | |
fea681da | 146 | The |
63aa9df0 | 147 | .BR ulckpwdf () |
fea681da MK |
148 | function releases the lock again. |
149 | Note that there is no protection against direct access of the shadow | |
c13182ef MK |
150 | password file. |
151 | Only programs that use | |
63aa9df0 | 152 | .BR lckpwdf () |
fea681da | 153 | will notice the lock. |
dd3568a1 | 154 | .PP |
05461740 | 155 | These were the functions that formed the original shadow API. |
fea681da MK |
156 | They are widely available. |
157 | .\" Also in libc5 | |
158 | .\" SUN doesn't have sgetspent() | |
73d8cece | 159 | .SS Reentrant versions |
05461740 MK |
160 | Analogous to the reentrant functions for the password database, glibc |
161 | also has reentrant functions for the shadow password database. | |
fea681da | 162 | The |
63aa9df0 | 163 | .BR getspnam_r () |
fea681da | 164 | function is like |
63aa9df0 | 165 | .BR getspnam () |
05461740 | 166 | but stores the retrieved shadow password structure in the space pointed to by |
fea681da | 167 | .IR spbuf . |
05461740 | 168 | This shadow password structure contains pointers to strings, and these strings |
fea681da MK |
169 | are stored in the buffer |
170 | .I buf | |
171 | of size | |
172 | .IR buflen . | |
173 | A pointer to the result (in case of success) or NULL (in case no entry | |
174 | was found or an error occurred) is stored in | |
bd9b2a9c | 175 | .IR *spbufp . |
dd3568a1 | 176 | .PP |
fea681da | 177 | The functions |
63aa9df0 MK |
178 | .BR getspent_r (), |
179 | .BR fgetspent_r (), | |
fea681da | 180 | and |
63aa9df0 | 181 | .BR sgetspent_r () |
54d75d6c | 182 | are similarly analogous to their nonreentrant counterparts. |
dd3568a1 | 183 | .PP |
fea681da MK |
184 | Some non-glibc systems also have functions with these names, |
185 | often with different prototypes. | |
186 | .\" SUN doesn't have sgetspent_r() | |
187 | .SS Structure | |
05461740 | 188 | The shadow password structure is defined in \fI<shadow.h>\fP as follows: |
51f5698d | 189 | .PP |
bd191423 | 190 | .in +4n |
b8302363 | 191 | .EX |
fea681da | 192 | struct spwd { |
8c5263f4 MK |
193 | char *sp_namp; /* Login name */ |
194 | char *sp_pwdp; /* Encrypted password */ | |
aed50605 MK |
195 | long sp_lstchg; /* Date of last change |
196 | (measured in days since | |
197 | 1970-01-01 00:00:00 +0000 (UTC)) */ | |
8c5263f4 MK |
198 | long sp_min; /* Min # of days between changes */ |
199 | long sp_max; /* Max # of days between changes */ | |
200 | long sp_warn; /* # of days before password expires | |
201 | to warn user to change it */ | |
202 | long sp_inact; /* # of days after password expires | |
203 | until account is disabled */ | |
aed50605 MK |
204 | long sp_expire; /* Date when account expires |
205 | (measured in days since | |
206 | 1970-01-01 00:00:00 +0000 (UTC)) */ | |
8c5263f4 | 207 | unsigned long sp_flag; /* Reserved */ |
fea681da | 208 | }; |
b8302363 | 209 | .EE |
bd191423 | 210 | .in |
47297adb | 211 | .SH RETURN VALUE |
05461740 MK |
212 | The functions that return a pointer return NULL if no more entries |
213 | are available or if an error occurs during processing. | |
a8d55537 | 214 | The functions which have \fIint\fP as the return value return 0 for |
c433dca4 MK |
215 | success and \-1 for failure, with |
216 | .I errno | |
217 | set to indicate the cause of the error. | |
dd3568a1 | 218 | .PP |
54d75d6c | 219 | For the nonreentrant functions, the return value may point to static area, |
fea681da | 220 | and may be overwritten by subsequent calls to these functions. |
dd3568a1 | 221 | .PP |
fea681da | 222 | The reentrant functions return zero on success. |
05461740 | 223 | In case of error, an error number is returned. |
fea681da MK |
224 | .SH ERRORS |
225 | .TP | |
5a39e7b5 MK |
226 | .B EACCES |
227 | The caller does not have permission to access the shadow password file. | |
228 | .TP | |
fea681da MK |
229 | .B ERANGE |
230 | Supplied buffer is too small. | |
231 | .SH FILES | |
232 | .TP | |
233 | .I /etc/shadow | |
05461740 | 234 | local shadow password database file |
fea681da MK |
235 | .TP |
236 | .I /etc/.pwd.lock | |
237 | lock file | |
dd3568a1 | 238 | .PP |
fea681da MK |
239 | The include file |
240 | .I <paths.h> | |
2f0af33b MK |
241 | defines the constant |
242 | .B _PATH_SHADOW | |
243 | to the pathname of the shadow password file. | |
557d7d96 ZL |
244 | .SH ATTRIBUTES |
245 | For an explanation of the terms used in this section, see | |
246 | .BR attributes (7). | |
247 | .TS | |
248 | allbox; | |
3a09fae8 | 249 | lbw13 lb lbw30 |
557d7d96 ZL |
250 | l l l. |
251 | Interface Attribute Value | |
252 | T{ | |
253 | .BR getspnam () | |
254 | T} Thread safety T{ | |
255 | MT-Unsafe race:getspnam locale | |
256 | T} | |
257 | T{ | |
258 | .BR getspent () | |
259 | T} Thread safety T{ | |
260 | MT-Unsafe race:getspent | |
261 | .br | |
262 | race:spentbuf locale | |
263 | T} | |
264 | T{ | |
265 | .BR setspent (), | |
3a09fae8 | 266 | .br |
557d7d96 ZL |
267 | .BR endspent (), |
268 | .br | |
269 | .BR getspent_r () | |
270 | T} Thread safety T{ | |
271 | MT-Unsafe race:getspent locale | |
272 | T} | |
273 | T{ | |
274 | .BR fgetspent () | |
275 | T} Thread safety MT-Unsafe race:fgetspent | |
276 | T{ | |
277 | .BR sgetspent () | |
278 | T} Thread safety MT-Unsafe race:sgetspent | |
279 | T{ | |
280 | .BR putspent (), | |
3a09fae8 | 281 | .br |
557d7d96 ZL |
282 | .BR getspnam_r (), |
283 | .br | |
284 | .BR sgetspent_r () | |
285 | T} Thread safety MT-Safe locale | |
286 | T{ | |
287 | .BR lckpwdf (), | |
3a09fae8 | 288 | .br |
557d7d96 ZL |
289 | .BR ulckpwdf (), |
290 | .br | |
291 | .BR fgetspent_r () | |
292 | T} Thread safety MT-Safe | |
293 | .TE | |
847e0d88 | 294 | .sp 1 |
557d7d96 ZL |
295 | In the above table, |
296 | .I getspent | |
297 | in | |
298 | .I race:getspent | |
299 | signifies that if any of the functions | |
344254ad MK |
300 | .BR setspent (), |
301 | .BR getspent (), | |
302 | .BR getspent_r (), | |
557d7d96 | 303 | or |
344254ad | 304 | .BR endspent () |
557d7d96 ZL |
305 | are used in parallel in different threads of a program, |
306 | then data races could occur. | |
47297adb | 307 | .SH CONFORMING TO |
c13182ef | 308 | The shadow password database and its associated API are |
c02b7e28 | 309 | not specified in POSIX.1. |
05461740 | 310 | However, many other systems provide a similar API. |
47297adb | 311 | .SH SEE ALSO |
fea681da MK |
312 | .BR getgrnam (3), |
313 | .BR getpwnam (3), | |
314 | .BR getpwnam_r (3), | |
cc4615cc | 315 | .BR shadow (5) |