1GETSPNAM(3) Linux Programmer's Manual GETSPNAM(3)
2
6 getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, fget‐
7 spent, fgetspent_r, sgetspent, sgetspent_r, putspent, lckpwdf, ulckpwdf
8 - get shadow password file entry
9
11 /* General shadow password file API */
12 #include <shadow.h>
13 struct spwd *getspnam(const char *name);
15 struct spwd *getspent(void);
17 void setspent(void);
19 void endspent(void);
21 struct spwd *fgetspent(FILE *stream);
23 struct spwd *sgetspent(const char *s);
25 int putspent(const struct spwd *p, FILE *stream);
27 int lckpwdf(void);
29 int ulckpwdf(void);
31 /* GNU extension */
33 #include <shadow.h>
34 int getspent_r(struct spwd *spbuf,
36 char *buf, size_t buflen, struct spwd **spbufp);
37 int getspnam_r(const char *name, struct spwd *spbuf,
39 char *buf, size_t buflen, struct spwd **spbufp);
40 int fgetspent_r(FILE *stream, struct spwd *spbuf,
42 char *buf, size_t buflen, struct spwd **spbufp);
43 int sgetspent_r(const char *s, struct spwd *spbuf,
45 char *buf, size_t buflen, struct spwd **spbufp);
46 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
48 getspent_r(), getspnam_r(), fgetspent_r(), sgetspent_r():
50 Since glibc 2.19:
51 _DEFAULT_SOURCE
52 Glibc 2.19 and earlier:
53 _BSD_SOURCE || _SVID_SOURCE
54
56 Long ago it was considered safe to have encrypted passwords openly vis‐
57 ible in the password file. When computers got faster and people got
58 more security-conscious, this was no longer acceptable. Julianne
59 Frances Haugh implemented the shadow password suite that keeps the
60 encrypted passwords in the shadow password database (e.g., the local
61 shadow password file /etc/shadow, NIS, and LDAP), readable only by
62 root.
63 The functions described below resemble those for the traditional pass‐
65 word database (e.g., see getpwnam(3) and getpwent(3)).
66 The getspnam() function returns a pointer to a structure containing the
68 broken-out fields of the record in the shadow password database that
69 matches the username name.
70 The getspent() function returns a pointer to the next entry in the
72 shadow password database. The position in the input stream is initial‐
73 ized by setspent(). When done reading, the program may call endspent()
74 so that resources can be deallocated.
75 The fgetspent() function is similar to getspent() but uses the supplied
77 stream instead of the one implicitly opened by setspent().
78 The sgetspent() function parses the supplied string s into a struct
80 spwd.
81 The putspent() function writes the contents of the supplied struct spwd
83 *p as a text line in the shadow password file format to stream. String
84 entries with value NULL and numerical entries with value -1 are written
85 as an empty string.
86 The lckpwdf() function is intended to protect against multiple simulta‐
88 neous accesses of the shadow password database. It tries to acquire a
89 lock, and returns 0 on success, or -1 on failure (lock not obtained
90 within 15 seconds). The ulckpwdf() function releases the lock again.
91 Note that there is no protection against direct access of the shadow
92 password file. Only programs that use lckpwdf() will notice the lock.
93 These were the functions that formed the original shadow API. They are
95 widely available.
96 Reentrant versions
98 Analogous to the reentrant functions for the password database, glibc
99 also has reentrant functions for the shadow password database. The
100 getspnam_r() function is like getspnam() but stores the retrieved
101 shadow password structure in the space pointed to by spbuf. This
102 shadow password structure contains pointers to strings, and these
103 strings are stored in the buffer buf of size buflen. A pointer to the
104 result (in case of success) or NULL (in case no entry was found or an
105 error occurred) is stored in *spbufp.
106 The functions getspent_r(), fgetspent_r(), and sgetspent_r() are simi‐
108 larly analogous to their nonreentrant counterparts.
109 Some non-glibc systems also have functions with these names, often with
111 different prototypes.
112 Structure
114 The shadow password structure is defined in <shadow.h> as follows:
115 struct spwd {
117 char *sp_namp; /* Login name */
118 char *sp_pwdp; /* Encrypted password */
119 long sp_lstchg; /* Date of last change
120 (measured in days since
121 1970-01-01 00:00:00 +0000 (UTC)) */
122 long sp_min; /* Min # of days between changes */
123 long sp_max; /* Max # of days between changes */
124 long sp_warn; /* # of days before password expires
125 to warn user to change it */
126 long sp_inact; /* # of days after password expires
127 until account is disabled */
128 long sp_expire; /* Date when account expires
129 (measured in days since
130 1970-01-01 00:00:00 +0000 (UTC)) */
131 unsigned long sp_flag; /* Reserved */
132 };
133
135 The functions that return a pointer return NULL if no more entries are
136 available or if an error occurs during processing. The functions which
137 have int as the return value return 0 for success and -1 for failure,
138 with errno set to indicate the cause of the error.
139 For the nonreentrant functions, the return value may point to static
141 area, and may be overwritten by subsequent calls to these functions.
142 The reentrant functions return zero on success. In case of error, an
144 error number is returned.
145
147 EACCES The caller does not have permission to access the shadow pass‐
148 word file.
149 ERANGE Supplied buffer is too small.
151
153 /etc/shadow
154 local shadow password database file
155 /etc/.pwd.lock
157 lock file
158 The include file <paths.h> defines the constant _PATH_SHADOW to the
160 pathname of the shadow password file.
161
163 For an explanation of the terms used in this section, see
164 attributes(7).
165 ┌──────────────┬───────────────┬────────────────────────────────┐
167 │Interface │ Attribute │ Value │
168 ├──────────────┼───────────────┼────────────────────────────────┤
169 │getspnam() │ Thread safety │ MT-Unsafe race:getspnam locale │
170 ├──────────────┼───────────────┼────────────────────────────────┤
171 │getspent() │ Thread safety │ MT-Unsafe race:getspent │
172 │ │ │ race:spentbuf locale │
173 ├──────────────┼───────────────┼────────────────────────────────┤
174 │setspent(), │ Thread safety │ MT-Unsafe race:getspent locale │
175 │endspent(), │ │ │
176 │getspent_r() │ │ │
177 ├──────────────┼───────────────┼────────────────────────────────┤
178 │fgetspent() │ Thread safety │ MT-Unsafe race:fgetspent │
179 ├──────────────┼───────────────┼────────────────────────────────┤
180 │sgetspent() │ Thread safety │ MT-Unsafe race:sgetspent │
181 ├──────────────┼───────────────┼────────────────────────────────┤
182 │putspent(), │ Thread safety │ MT-Safe locale │
183 │getspnam_r(), │ │ │
184 │sgetspent_r() │ │ │
185 ├──────────────┼───────────────┼────────────────────────────────┤
186 │lckpwdf(), │ Thread safety │ MT-Safe │
187 │ulckpwdf(), │ │ │
188 │fgetspent_r() │ │ │
189 └──────────────┴───────────────┴────────────────────────────────┘
190 In the above table, getspent in race:getspent signifies that if any of
191 the functions setspent(), getspent(), getspent_r(), or endspent() are
192 used in parallel in different threads of a program, then data races
193 could occur.
194
196 The shadow password database and its associated API are not specified
197 in POSIX.1. However, many other systems provide a similar API.
198
200 getgrnam(3), getpwnam(3), getpwnam_r(3), shadow(5)
201
203 This page is part of release 4.16 of the Linux man-pages project. A
204 description of the project, information about reporting bugs, and the
205 latest version of this page, can be found at
206 https://www.kernel.org/doc/man-pages/.
207GNU 2017-09-15 GETSPNAM(3)