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