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