]>
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 | .\" | |
4 | .\" Distributed under GPL | |
5 | .\" | |
cc4615cc | 6 | .TH GETSPNAM 3 2007-07-26 "GNU" "Linux Programmer's Manual" |
fea681da MK |
7 | .SH NAME |
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 | |
11 | .SH SYNOPSIS | |
12 | .nf | |
13 | /* General shadow password file API */ | |
14 | .br | |
15 | .B #include <shadow.h> | |
16 | .sp | |
17 | .BI "struct spwd *getspnam(const char *" name ); | |
18 | .sp | |
19 | .B struct spwd *getspent(void); | |
20 | .sp | |
21 | .B void setspent(void); | |
22 | .sp | |
23 | .B void endspent(void); | |
24 | .sp | |
25 | .BI "struct spwd *fgetspent(FILE *" fp ); | |
26 | .sp | |
27 | .BI "struct spwd *sgetspent(const char *" s ); | |
28 | .sp | |
29 | .BI "int putspent(struct spwd *" p ", FILE *" fp ); | |
30 | .sp | |
31 | .B int lckpwdf(void); | |
32 | .sp | |
33 | .B int ulckpwdf(void); | |
34 | .sp | |
35 | /* GNU extension */ | |
36 | .br | |
fea681da MK |
37 | .B #include <shadow.h> |
38 | .sp | |
39 | .BI "int getspent_r(struct spwd *" spbuf , | |
40 | .br | |
41 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); | |
42 | .sp | |
43 | .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , | |
44 | .br | |
45 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); | |
46 | .sp | |
47 | .BI "int fgetspent_r(FILE *" fp ", struct spwd *" spbuf , | |
48 | .br | |
49 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); | |
50 | .sp | |
51 | .BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf , | |
52 | .br | |
53 | .BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp ); | |
fea681da | 54 | .fi |
cc4615cc MK |
55 | .sp |
56 | .in -4n | |
57 | Feature Test Macro Requirements for glibc (see | |
58 | .BR feature_test_macros (7)): | |
59 | .in | |
60 | .sp | |
61 | .ad l | |
62 | .BR getspent_r (), | |
63 | .BR getspnam_r (), | |
64 | .BR fgetspent_r (), | |
65 | .BR sgetspent_r (): | |
66 | _BSD_SOURCE || _SVID_SOURCE | |
67 | .ad b | |
fea681da MK |
68 | .SH DESCRIPTION |
69 | Long ago it was considered safe to have encrypted passwords openly | |
c13182ef MK |
70 | visible in the password file. |
71 | When computers got faster and people | |
fea681da MK |
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 | |
05461740 | 75 | the shadow password database |
c13182ef | 76 | (e.g., the local shadow password file |
fea681da | 77 | .IR /etc/shadow , |
05461740 | 78 | NIS, and LDAP), |
fea681da MK |
79 | readable only by root. |
80 | .LP | |
05461740 MK |
81 | The functions described below resemble those for |
82 | the traditional password database | |
83 | (e.g., see | |
84 | .BR getpwnam (3) | |
85 | and | |
86 | .BR getpwent (3)). | |
777f5a9e | 87 | .\" FIXME I've commented out the following for the |
c13182ef MK |
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. | |
777f5a9e | 91 | .\" (Jul 2005, mtk) |
c13182ef MK |
92 | .\" |
93 | .\" This shadow password setup has been superseded by PAM | |
05461740 MK |
94 | .\" (pluggable authentication modules), and the file |
95 | .\" .I /etc/nsswitch.conf | |
96 | .\" now describes the sources to be used. | |
fea681da MK |
97 | .LP |
98 | The | |
63aa9df0 | 99 | .BR getspnam () |
fea681da | 100 | function returns a pointer to a structure containing |
05461740 MK |
101 | the broken-out fields of the record in the shadow password database |
102 | that matches the user name | |
fea681da MK |
103 | .IR name . |
104 | .LP | |
105 | The | |
63aa9df0 | 106 | .BR getspent () |
05461740 MK |
107 | function returns a pointer to the next entry in the shadow password |
108 | database. | |
fea681da | 109 | The position in the input stream is initialized by |
63aa9df0 | 110 | .BR setspent (). |
fea681da | 111 | When done reading, the program may call |
63aa9df0 | 112 | .BR endspent () |
fea681da MK |
113 | so that resources can be deallocated. |
114 | .\" some systems require a call of setspent() before the first getspent() | |
115 | .\" glibc does not | |
116 | .LP | |
117 | The | |
63aa9df0 | 118 | .BR fgetspent () |
fea681da | 119 | function is similar to |
63aa9df0 | 120 | .BR getspent () |
fea681da | 121 | but uses the supplied stream instead of the one implicitly opened by |
63aa9df0 | 122 | .BR setspent (). |
fea681da MK |
123 | .LP |
124 | The | |
63aa9df0 | 125 | .BR sgetspent () |
fea681da MK |
126 | function parses the supplied string |
127 | .I s | |
05461740 MK |
128 | into a struct |
129 | .IR spwd . | |
fea681da MK |
130 | .LP |
131 | The | |
63aa9df0 | 132 | .BR putspent () |
05461740 MK |
133 | function writes the contents of the supplied struct |
134 | .I spwd | |
fea681da MK |
135 | .RI * p |
136 | as a text line in the shadow password file format to the stream | |
137 | .IR fp . | |
138 | String entries with value NULL and numerical entries with value \-1 | |
139 | are written as an empty string. | |
140 | .LP | |
141 | The | |
63aa9df0 | 142 | .BR lckpwdf () |
c13182ef | 143 | function is intended to protect against multiple simultaneous accesses |
05461740 MK |
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). | |
fea681da | 147 | The |
63aa9df0 | 148 | .BR ulckpwdf () |
fea681da MK |
149 | function releases the lock again. |
150 | Note that there is no protection against direct access of the shadow | |
c13182ef MK |
151 | password file. |
152 | Only programs that use | |
63aa9df0 | 153 | .BR lckpwdf () |
fea681da MK |
154 | will notice the lock. |
155 | .LP | |
05461740 | 156 | These were the functions that formed the original shadow API. |
fea681da MK |
157 | They are widely available. |
158 | .\" Also in libc5 | |
159 | .\" SUN doesn't have sgetspent() | |
160 | .SS "Reentrant versions" | |
05461740 MK |
161 | Analogous to the reentrant functions for the password database, glibc |
162 | also has reentrant functions for the shadow password database. | |
fea681da | 163 | The |
63aa9df0 | 164 | .BR getspnam_r () |
fea681da | 165 | function is like |
63aa9df0 | 166 | .BR getspnam () |
05461740 | 167 | but stores the retrieved shadow password structure in the space pointed to by |
fea681da | 168 | .IR spbuf . |
05461740 | 169 | This shadow password structure contains pointers to strings, and these strings |
fea681da MK |
170 | are stored in the buffer |
171 | .I buf | |
172 | of size | |
173 | .IR buflen . | |
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 | |
176 | .RI * spbufp . | |
177 | .LP | |
178 | The functions | |
63aa9df0 MK |
179 | .BR getspent_r (), |
180 | .BR fgetspent_r (), | |
fea681da | 181 | and |
63aa9df0 | 182 | .BR sgetspent_r () |
05461740 | 183 | are similarly analogous to their non-reentrant counterparts. |
fea681da MK |
184 | .LP |
185 | Some non-glibc systems also have functions with these names, | |
186 | often with different prototypes. | |
187 | .\" SUN doesn't have sgetspent_r() | |
188 | .SS Structure | |
05461740 | 189 | The shadow password structure is defined in \fI<shadow.h>\fP as follows: |
fea681da | 190 | .sp |
05461740 | 191 | .RS +0.25i |
fea681da MK |
192 | .nf |
193 | struct spwd { | |
194 | char *sp_namp; /* Login name */ | |
195 | char *sp_pwdp; /* Encrypted password */ | |
05461740 MK |
196 | long sp_lstchg; /* Date of last change */ |
197 | long sp_min; /* Min #days between changes */ | |
198 | long sp_max; /* Max #days between changes */ | |
199 | long sp_warn; /* #days before pwd expires | |
fea681da | 200 | to warn user to change it */ |
05461740 | 201 | long sp_inact; /* #days after pwd expires |
fea681da | 202 | until account is disabled */ |
05461740 | 203 | long sp_expire; /* #days since 1970-01-01 |
fea681da MK |
204 | until account is disabled */ |
205 | unsigned long sp_flag; /* Reserved */ | |
206 | }; | |
207 | .fi | |
05461740 | 208 | .RE |
fea681da | 209 | .SH "RETURN VALUE" |
05461740 MK |
210 | The functions that return a pointer return NULL if no more entries |
211 | are available or if an error occurs during processing. | |
a8d55537 | 212 | The functions which have \fIint\fP as the return value return 0 for |
8729177b | 213 | success and \-1 for failure. |
fea681da MK |
214 | .LP |
215 | For the non-reentrant functions, the return value may point to static area, | |
216 | and may be overwritten by subsequent calls to these functions. | |
217 | .LP | |
218 | The reentrant functions return zero on success. | |
05461740 | 219 | In case of error, an error number is returned. |
fea681da MK |
220 | .SH ERRORS |
221 | .TP | |
222 | .B ERANGE | |
223 | Supplied buffer is too small. | |
224 | .SH FILES | |
225 | .TP | |
226 | .I /etc/shadow | |
05461740 | 227 | local shadow password database file |
fea681da MK |
228 | .TP |
229 | .I /etc/.pwd.lock | |
230 | lock file | |
231 | .LP | |
232 | The include file | |
233 | .I <paths.h> | |
2f0af33b MK |
234 | defines the constant |
235 | .B _PATH_SHADOW | |
236 | to the pathname of the shadow password file. | |
fea681da | 237 | .SH "CONFORMING TO" |
c13182ef | 238 | The shadow password database and its associated API are |
05461740 MK |
239 | not specified in POSIX.1-2001. |
240 | However, many other systems provide a similar API. | |
fea681da MK |
241 | .SH "SEE ALSO" |
242 | .BR getgrnam (3), | |
243 | .BR getpwnam (3), | |
244 | .BR getpwnam_r (3), | |
cc4615cc | 245 | .BR shadow (5) |