1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and
2 .\" Walter Harms (walter.harms@informatik.uni-oldenburg.de)
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" Distributed under GPL
8 .TH GETSPNAM 3 2014-05-28 "GNU" "Linux Programmer's Manual"
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
15 /* General shadow password file API */
17 .B #include <shadow.h>
19 .BI "struct spwd *getspnam(const char *" name );
21 .B struct spwd *getspent(void);
23 .B void setspent(void);
25 .B void endspent(void);
27 .BI "struct spwd *fgetspent(FILE *" fp );
29 .BI "struct spwd *sgetspent(const char *" s );
31 .BI "int putspent(const struct spwd *" p ", FILE *" fp );
35 .B int ulckpwdf(void);
39 .B #include <shadow.h>
41 .BI "int getspent_r(struct spwd *" spbuf ,
43 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
45 .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf ,
47 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
49 .BI "int fgetspent_r(FILE *" fp ", struct spwd *" spbuf ,
51 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
53 .BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf ,
55 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
59 Feature Test Macro Requirements for glibc (see
60 .BR feature_test_macros (7)):
69 _BSD_SOURCE || _SVID_SOURCE
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
83 readable only by root.
85 The functions described below resemble those for
86 the traditional password database
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.
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.
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
111 function returns a pointer to the next entry in the shadow password
113 The position in the input stream is initialized by
115 When done reading, the program may call
117 so that resources can be deallocated.
118 .\" some systems require a call of setspent() before the first getspent()
123 function is similar to
125 but uses the supplied stream instead of the one implicitly opened by
130 function parses the supplied string
137 function writes the contents of the supplied struct
140 as a text line in the shadow password file format to the stream
142 String entries with value NULL and numerical entries with value \-1
143 are written as an empty string.
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).
153 function releases the lock again.
154 Note that there is no protection against direct access of the shadow
156 Only programs that use
158 will notice the lock.
160 These were the functions that formed the original shadow API.
161 They are widely available.
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.
171 but stores the retrieved shadow password structure in the space pointed to by
173 This shadow password structure contains pointers to strings, and these strings
174 are stored in the buffer
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
187 are similarly analogous to their nonreentrant counterparts.
189 Some non-glibc systems also have functions with these names,
190 often with different prototypes.
191 .\" SUN doesn't have sgetspent_r()
193 The shadow password structure is defined in \fI<shadow.h>\fP as follows:
198 char *sp_namp; /* Login name */
199 char *sp_pwdp; /* Encrypted password */
200 long sp_lstchg; /* Date of last change
201 (measured in days since
202 1970-01-01 00:00:00 +0000 (UTC)) */
203 long sp_min; /* Min # of days between changes */
204 long sp_max; /* Max # of days between changes */
205 long sp_warn; /* # of days before password expires
206 to warn user to change it */
207 long sp_inact; /* # of days after password expires
208 until account is disabled */
209 long sp_expire; /* Date when account expires
210 (measured in days since
211 1970-01-01 00:00:00 +0000 (UTC)) */
212 unsigned long sp_flag; /* Reserved */
217 The functions that return a pointer return NULL if no more entries
218 are available or if an error occurs during processing.
219 The functions which have \fIint\fP as the return value return 0 for
220 success and \-1 for failure, with
222 set to indicate the cause of the error.
224 For the nonreentrant functions, the return value may point to static area,
225 and may be overwritten by subsequent calls to these functions.
227 The reentrant functions return zero on success.
228 In case of error, an error number is returned.
232 The caller does not have permission to access the shadow password file.
235 Supplied buffer is too small.
239 local shadow password database file
248 to the pathname of the shadow password file.
250 The shadow password database and its associated API are
251 not specified in POSIX.1-2001.
252 However, many other systems provide a similar API.
259 This page is part of release 3.68 of the Linux
262 A description of the project,
263 information about reporting bugs,
264 and the latest version of this page,
266 \%http://www.kernel.org/doc/man\-pages/.