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