1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and
2 .\" Walter Harms (walter.harms@informatik.uni-oldenburg.de)
4 .\" Distributed under GPL
6 .TH GETSPNAM 3 2008-07-09 "GNU" "Linux Programmer's Manual"
8 getspnam, getspnam_r, getspent, getspent_r, setspent, endspent,
9 fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent,
10 lckpwdf, ulckpwdf \- get shadow password file entry
13 /* General shadow password file API */
15 .B #include <shadow.h>
17 .BI "struct spwd *getspnam(const char *" name );
19 .B struct spwd *getspent(void);
21 .B void setspent(void);
23 .B void endspent(void);
25 .BI "struct spwd *fgetspent(FILE *" fp );
27 .BI "struct spwd *sgetspent(const char *" s );
29 .BI "int putspent(struct spwd *" p ", FILE *" fp );
33 .B int ulckpwdf(void);
37 .B #include <shadow.h>
39 .BI "int getspent_r(struct spwd *" spbuf ,
41 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
43 .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf ,
45 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
47 .BI "int fgetspent_r(FILE *" fp ", struct spwd *" spbuf ,
49 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
51 .BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf ,
53 .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
57 Feature Test Macro Requirements for glibc (see
58 .BR feature_test_macros (7)):
66 _BSD_SOURCE || _SVID_SOURCE
69 Long ago it was considered safe to have encrypted passwords openly
70 visible in the password file.
71 When computers got faster and people
72 got more security-conscious, this was no longer acceptable.
73 Julianne Frances Haugh implemented the shadow password suite
74 that keeps the encrypted passwords in
75 the shadow password database
76 (e.g., the local shadow password file
79 readable only by root.
81 The functions described below resemble those for
82 the traditional password database
87 .\" FIXME I've commented out the following for the
88 .\" moment. The relationship between PAM and nsswitch.conf needs
89 .\" to be clearly documented in one place, which is pointed to by
90 .\" the pages for the user, group, and shadow password functions.
93 .\" This shadow password setup has been superseded by PAM
94 .\" (pluggable authentication modules), and the file
95 .\" .I /etc/nsswitch.conf
96 .\" now describes the sources to be used.
100 function returns a pointer to a structure containing
101 the broken-out fields of the record in the shadow password database
102 that matches the username
107 function returns a pointer to the next entry in the shadow password
109 The position in the input stream is initialized by
111 When done reading, the program may call
113 so that resources can be deallocated.
114 .\" some systems require a call of setspent() before the first getspent()
119 function is similar to
121 but uses the supplied stream instead of the one implicitly opened by
126 function parses the supplied string
133 function writes the contents of the supplied struct
136 as a text line in the shadow password file format to the stream
138 String entries with value NULL and numerical entries with value \-1
139 are written as an empty string.
143 function is intended to protect against multiple simultaneous accesses
144 of the shadow password database.
145 It tries to acquire a lock, and returns 0 on success,
146 or \-1 on failure (lock not obtained within 15 seconds).
149 function releases the lock again.
150 Note that there is no protection against direct access of the shadow
152 Only programs that use
154 will notice the lock.
156 These were the functions that formed the original shadow API.
157 They are widely available.
159 .\" SUN doesn't have sgetspent()
160 .SS "Reentrant versions"
161 Analogous to the reentrant functions for the password database, glibc
162 also has reentrant functions for the shadow password database.
167 but stores the retrieved shadow password structure in the space pointed to by
169 This shadow password structure contains pointers to strings, and these strings
170 are stored in the buffer
174 A pointer to the result (in case of success) or NULL (in case no entry
175 was found or an error occurred) is stored in
183 are similarly analogous to their nonreentrant counterparts.
185 Some non-glibc systems also have functions with these names,
186 often with different prototypes.
187 .\" SUN doesn't have sgetspent_r()
189 The shadow password structure is defined in \fI<shadow.h>\fP as follows:
194 char *sp_namp; /* Login name */
195 char *sp_pwdp; /* Encrypted password */
196 long sp_lstchg; /* Date of last change (measured
197 in days since 1970-01-01 00:00:00 +0000 (UTC)) */
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 */
204 long sp_expire; /* Date when account expires (measured
205 in days since 1970-01-01 00:00:00 +0000 (UTC)) */
206 unsigned long sp_flag; /* Reserved */
211 The functions that return a pointer return NULL if no more entries
212 are available or if an error occurs during processing.
213 The functions which have \fIint\fP as the return value return 0 for
214 success and \-1 for failure.
216 For the nonreentrant functions, the return value may point to static area,
217 and may be overwritten by subsequent calls to these functions.
219 The reentrant functions return zero on success.
220 In case of error, an error number is returned.
224 Supplied buffer is too small.
228 local shadow password database file
237 to the pathname of the shadow password file.
239 The shadow password database and its associated API are
240 not specified in POSIX.1-2001.
241 However, many other systems provide a similar API.