man3/getspnam.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and
   2 .\" Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" Distributed under GPL
   6 .\" %%%LICENSE_END
   7 .\"
   8 .TH GETSPNAM 3  2021-03-22 "GNU" "Linux Programmer's Manual"
   9 .SH NAME
  10 getspnam, getspnam_r, getspent, getspent_r, setspent, endspent,
  11 fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent,
  12 lckpwdf, ulckpwdf \- get shadow password file entry
  13 .SH SYNOPSIS
  14 .nf
  15 /* General shadow password file API */
  16 .B #include <shadow.h>
  17 .PP
  18 .BI "struct spwd *getspnam(const char *" name );
  19 .B struct spwd *getspent(void);
  20 .PP
  21 .B void setspent(void);
  22 .B void endspent(void);
  23 .PP
  24 .BI "struct spwd *fgetspent(FILE *" stream );
  25 .BI "struct spwd *sgetspent(const char *" s );
  26 .PP
  27 .BI "int putspent(const struct spwd *" p ", FILE *" stream );
  28 .PP
  29 .B int lckpwdf(void);
  30 .B int ulckpwdf(void);
  31 .PP
  32 /* GNU extension */
  33 .B #include <shadow.h>
  34 .PP
  35 .BI "int getspent_r(struct spwd *" spbuf ,
  36 .BI "               char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  37 .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf ,
  38 .BI "               char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  39 .PP
  40 .BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf ,
  41 .BI "               char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  42 .BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf ,
  43 .BI "               char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  44 .fi
  45 .PP
  46 .RS -4
  47 Feature Test Macro Requirements for glibc (see
  48 .BR feature_test_macros (7)):
  49 .RE
  50 .PP
  51 .BR getspent_r (),
  52 .BR getspnam_r (),
  53 .BR fgetspent_r (),
  54 .BR sgetspent_r ():
  55 .nf
  56     Since glibc 2.19:
  57         _DEFAULT_SOURCE
  58     Glibc 2.19 and earlier:
  59         _BSD_SOURCE || _SVID_SOURCE
  60 .fi
  61 .SH DESCRIPTION
  62 Long ago it was considered safe to have encrypted passwords openly
  63 visible in the password file.
  64 When computers got faster and people
  65 got more security-conscious, this was no longer acceptable.
  66 Julianne Frances Haugh implemented the shadow password suite
  67 that keeps the encrypted passwords in
  68 the shadow password database
  69 (e.g., the local shadow password file
  70 .IR /etc/shadow ,
  71 NIS, and LDAP),
  72 readable only by root.
  73 .PP
  74 The functions described below resemble those for
  75 the traditional password database
  76 (e.g., see
  77 .BR getpwnam (3)
  78 and
  79 .BR getpwent (3)).
  80 .\" FIXME . I've commented out the following for the
  81 .\" moment.  The relationship between PAM and nsswitch.conf needs
  82 .\" to be clearly documented in one place, which is pointed to by
  83 .\" the pages for the user, group, and shadow password functions.
  84 .\" (Jul 2005, mtk)
  85 .\"
  86 .\" This shadow password setup has been superseded by PAM
  87 .\" (pluggable authentication modules), and the file
  88 .\" .I /etc/nsswitch.conf
  89 .\" now describes the sources to be used.
  90 .PP
  91 The
  92 .BR getspnam ()
  93 function returns a pointer to a structure containing
  94 the broken-out fields of the record in the shadow password database
  95 that matches the username
  96 .IR name .
  97 .PP
  98 The
  99 .BR getspent ()
 100 function returns a pointer to the next entry in the shadow password
 101 database.
 102 The position in the input stream is initialized by
 103 .BR setspent ().
 104 When done reading, the program may call
 105 .BR endspent ()
 106 so that resources can be deallocated.
 107 .\" some systems require a call of setspent() before the first getspent()
 108 .\" glibc does not
 109 .PP
 110 The
 111 .BR fgetspent ()
 112 function is similar to
 113 .BR getspent ()
 114 but uses the supplied stream instead of the one implicitly opened by
 115 .BR setspent ().
 116 .PP
 117 The
 118 .BR sgetspent ()
 119 function parses the supplied string
 120 .I s
 121 into a struct
 122 .IR spwd .
 123 .PP
 124 The
 125 .BR putspent ()
 126 function writes the contents of the supplied struct
 127 .I spwd
 128 .I *p
 129 as a text line in the shadow password file format to
 130 .IR stream .
 131 String entries with value NULL and numerical entries with value \-1
 132 are written as an empty string.
 133 .PP
 134 The
 135 .BR lckpwdf ()
 136 function is intended to protect against multiple simultaneous accesses
 137 of the shadow password database.
 138 It tries to acquire a lock, and returns 0 on success,
 139 or \-1 on failure (lock not obtained within 15 seconds).
 140 The
 141 .BR ulckpwdf ()
 142 function releases the lock again.
 143 Note that there is no protection against direct access of the shadow
 144 password file.
 145 Only programs that use
 146 .BR lckpwdf ()
 147 will notice the lock.
 148 .PP
 149 These were the functions that formed the original shadow API.
 150 They are widely available.
 151 .\" Also in libc5
 152 .\" SUN doesn't have sgetspent()
 153 .SS Reentrant versions
 154 Analogous to the reentrant functions for the password database, glibc
 155 also has reentrant functions for the shadow password database.
 156 The
 157 .BR getspnam_r ()
 158 function is like
 159 .BR getspnam ()
 160 but stores the retrieved shadow password structure in the space pointed to by
 161 .IR spbuf .
 162 This shadow password structure contains pointers to strings, and these strings
 163 are stored in the buffer
 164 .I buf
 165 of size
 166 .IR buflen .
 167 A pointer to the result (in case of success) or NULL (in case no entry
 168 was found or an error occurred) is stored in
 169 .IR *spbufp .
 170 .PP
 171 The functions
 172 .BR getspent_r (),
 173 .BR fgetspent_r (),
 174 and
 175 .BR sgetspent_r ()
 176 are similarly analogous to their nonreentrant counterparts.
 177 .PP
 178 Some non-glibc systems also have functions with these names,
 179 often with different prototypes.
 180 .\" SUN doesn't have sgetspent_r()
 181 .SS Structure
 182 The shadow password structure is defined in \fI<shadow.h>\fP as follows:
 183 .PP
 184 .in +4n
 185 .EX
 186 struct spwd {
 187     char *sp_namp;     /* Login name */
 188     char *sp_pwdp;     /* Encrypted password */
 189     long  sp_lstchg;   /* Date of last change
 190                           (measured in days since
 191                           1970\-01\-01 00:00:00 +0000 (UTC)) */
 192     long  sp_min;      /* Min # of days between changes */
 193     long  sp_max;      /* Max # of days between changes */
 194     long  sp_warn;     /* # of days before password expires
 195                           to warn user to change it */
 196     long  sp_inact;    /* # of days after password expires
 197                           until account is disabled */
 198     long  sp_expire;   /* Date when account expires
 199                           (measured in days since
 200                           1970\-01\-01 00:00:00 +0000 (UTC)) */
 201     unsigned long sp_flag;  /* Reserved */
 202 };
 203 .EE
 204 .in
 205 .SH RETURN VALUE
 206 The functions that return a pointer return NULL if no more entries
 207 are available or if an error occurs during processing.
 208 The functions which have \fIint\fP as the return value return 0 for
 209 success and \-1 for failure, with
 210 .I errno
 211 set to indicate the error.
 212 .PP
 213 For the nonreentrant functions, the return value may point to static area,
 214 and may be overwritten by subsequent calls to these functions.
 215 .PP
 216 The reentrant functions return zero on success.
 217 In case of error, an error number is returned.
 218 .SH ERRORS
 219 .TP
 220 .B EACCES
 221 The caller does not have permission to access the shadow password file.
 222 .TP
 223 .B ERANGE
 224 Supplied buffer is too small.
 225 .SH FILES
 226 .TP
 227 .I /etc/shadow
 228 local shadow password database file
 229 .TP
 230 .I /etc/.pwd.lock
 231 lock file
 232 .PP
 233 The include file
 234 .I <paths.h>
 235 defines the constant
 236 .B _PATH_SHADOW
 237 to the pathname of the shadow password file.
 238 .SH ATTRIBUTES
 239 For an explanation of the terms used in this section, see
 240 .BR attributes (7).
 241 .ad l
 242 .nh
 243 .TS
 244 allbox;
 245 lb lb lbx
 246 l l l.
 247 Interface       Attribute       Value
 248 T{
 249 .BR getspnam ()
 250 T}      Thread safety   T{
 251 MT-Unsafe race:getspnam locale
 252 T}
 253 T{
 254 .BR getspent ()
 255 T}      Thread safety   T{
 256 MT-Unsafe race:getspent
 257 race:spentbuf locale
 258 T}
 259 T{
 260 .BR setspent (),
 261 .BR endspent (),
 262 .BR getspent_r ()
 263 T}      Thread safety   T{
 264 MT-Unsafe race:getspent locale
 265 T}
 266 T{
 267 .BR fgetspent ()
 268 T}      Thread safety   T{
 269 MT-Unsafe race:fgetspent
 270 T}
 271 T{
 272 .BR sgetspent ()
 273 T}      Thread safety   T{
 274 MT-Unsafe race:sgetspent
 275 T}
 276 T{
 277 .BR putspent (),
 278 .BR getspnam_r (),
 279 .BR sgetspent_r ()
 280 T}      Thread safety   T{
 281 MT-Safe locale
 282 T}
 283 T{
 284 .BR lckpwdf (),
 285 .BR ulckpwdf (),
 286 .BR fgetspent_r ()
 287 T}      Thread safety   T{
 288 MT-Safe
 289 T}
 290 .TE
 291 .hy
 292 .ad
 293 .sp 1
 294 In the above table,
 295 .I getspent
 296 in
 297 .I race:getspent
 298 signifies that if any of the functions
 299 .BR setspent (),
 300 .BR getspent (),
 301 .BR getspent_r (),
 302 or
 303 .BR endspent ()
 304 are used in parallel in different threads of a program,
 305 then data races could occur.
 306 .SH CONFORMING TO
 307 The shadow password database and its associated API are
 308 not specified in POSIX.1.
 309 However, many other systems provide a similar API.
 310 .SH SEE ALSO
 311 .BR getgrnam (3),
 312 .BR getpwnam (3),
 313 .BR getpwnam_r (3),
 314 .BR shadow (5)