1GETSPNAM(3)                Linux Programmer's Manual               GETSPNAM(3)
2
3
4

NAME

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

SYNOPSIS

11       /* General shadow password file API */
12       #include <shadow.h>
13
14       struct spwd *getspnam(const char *name);
15
16       struct spwd *getspent(void);
17
18       void setspent(void);
19
20       void endspent(void);
21
22       struct spwd *fgetspent(FILE *stream);
23
24       struct spwd *sgetspent(const char *s);
25
26       int putspent(const struct spwd *p, FILE *stream);
27
28       int lckpwdf(void);
29
30       int ulckpwdf(void);
31
32       /* GNU extension */
33       #include <shadow.h>
34
35       int getspent_r(struct spwd *spbuf,
36               char *buf, size_t buflen, struct spwd **spbufp);
37
38       int getspnam_r(const char *name, struct spwd *spbuf,
39               char *buf, size_t buflen, struct spwd **spbufp);
40
41       int fgetspent_r(FILE *stream, struct spwd *spbuf,
42               char *buf, size_t buflen, struct spwd **spbufp);
43
44       int sgetspent_r(const char *s, struct spwd *spbuf,
45               char *buf, size_t buflen, struct spwd **spbufp);
46
47   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
48
49       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

DESCRIPTION

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
64       The  functions described below resemble those for the traditional pass‐
65       word database (e.g., see getpwnam(3) and getpwent(3)).
66
67       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
71       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
76       The fgetspent() function is similar to getspent() but uses the supplied
77       stream instead of the one implicitly opened by setspent().
78
79       The sgetspent() function parses the supplied string  s  into  a  struct
80       spwd.
81
82       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
87       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
94       These were the functions that formed the original shadow API.  They are
95       widely available.
96
97   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
107       The  functions getspent_r(), fgetspent_r(), and sgetspent_r() are simi‐
108       larly analogous to their nonreentrant counterparts.
109
110       Some non-glibc systems also have functions with these names, often with
111       different prototypes.
112
113   Structure
114       The shadow password structure is defined in <shadow.h> as follows:
115
116           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

RETURN VALUE

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
140       For the nonreentrant functions, the return value may  point  to  static
141       area, and may be overwritten by subsequent calls to these functions.
142
143       The  reentrant  functions return zero on success.  In case of error, an
144       error number is returned.
145

ERRORS

147       EACCES The caller does not have permission to access the  shadow  pass‐
148              word file.
149
150       ERANGE Supplied buffer is too small.
151

FILES

153       /etc/shadow
154              local shadow password database file
155
156       /etc/.pwd.lock
157              lock file
158
159       The  include  file  <paths.h>  defines the constant _PATH_SHADOW to the
160       pathname of the shadow password file.
161

ATTRIBUTES

163       For  an  explanation  of  the  terms  used   in   this   section,   see
164       attributes(7).
165
166       ┌──────────────┬───────────────┬────────────────────────────────┐
167Interface     Attribute     Value                          
168       ├──────────────┼───────────────┼────────────────────────────────┤
169getspnam()    │ Thread safety │ MT-Unsafe race:getspnam locale │
170       ├──────────────┼───────────────┼────────────────────────────────┤
171getspent()    │ Thread safety │ MT-Unsafe race:getspent        │
172       │              │               │ race:spentbuf locale           │
173       ├──────────────┼───────────────┼────────────────────────────────┤
174setspent(),   │ Thread safety │ MT-Unsafe race:getspent locale │
175endspent(),   │               │                                │
176getspent_r()  │               │                                │
177       ├──────────────┼───────────────┼────────────────────────────────┤
178fgetspent()   │ Thread safety │ MT-Unsafe race:fgetspent       │
179       ├──────────────┼───────────────┼────────────────────────────────┤
180sgetspent()   │ Thread safety │ MT-Unsafe race:sgetspent       │
181       ├──────────────┼───────────────┼────────────────────────────────┤
182putspent(),   │ Thread safety │ MT-Safe locale                 │
183getspnam_r(), │               │                                │
184sgetspent_r() │               │                                │
185       ├──────────────┼───────────────┼────────────────────────────────┤
186lckpwdf(),    │ Thread safety │ MT-Safe                        │
187ulckpwdf(),   │               │                                │
188fgetspent_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

CONFORMING TO

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

SEE ALSO

200       getgrnam(3), getpwnam(3), getpwnam_r(3), shadow(5)
201

COLOPHON

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/.
207
208
209
210GNU                               2017-09-15                       GETSPNAM(3)
Impressum