Debian Codegraph @

upstream/debian-unstable/man3/getspnam.3

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