original/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  2013-04-19 "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 *" fp );
  28 .sp
  29 .BI "struct spwd *sgetspent(const char *" s );
  30 .sp
  31 .BI "int putspent(struct spwd *" p ", FILE *" fp );
  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 *" fp ", 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 .RS 4
  69 _BSD_SOURCE || _SVID_SOURCE
  70 .RE
  71 .ad b
  72 .SH DESCRIPTION
  73 Long ago it was considered safe to have encrypted passwords openly
  74 visible in the password file.
  75 When computers got faster and people
  76 got more security-conscious, this was no longer acceptable.
  77 Julianne Frances Haugh implemented the shadow password suite
  78 that keeps the encrypted passwords in
  79 the shadow password database
  80 (e.g., the local shadow password file
  81 .IR /etc/shadow ,
  82 NIS, and LDAP),
  83 readable only by root.
  84 .LP
  85 The functions described below resemble those for
  86 the traditional password database
  87 (e.g., see
  88 .BR getpwnam (3)
  89 and
  90 .BR getpwent (3)).
  91 .\" FIXME I've commented out the following for the
  92 .\" moment.  The relationship between PAM and nsswitch.conf needs
  93 .\" to be clearly documented in one place, which is pointed to by
  94 .\" the pages for the user, group, and shadow password functions.
  95 .\" (Jul 2005, mtk)
  96 .\"
  97 .\" This shadow password setup has been superseded by PAM
  98 .\" (pluggable authentication modules), and the file
  99 .\" .I /etc/nsswitch.conf
 100 .\" now describes the sources to be used.
 101 .LP
 102 The
 103 .BR getspnam ()
 104 function returns a pointer to a structure containing
 105 the broken-out fields of the record in the shadow password database
 106 that matches the username
 107 .IR name .
 108 .LP
 109 The
 110 .BR getspent ()
 111 function returns a pointer to the next entry in the shadow password
 112 database.
 113 The position in the input stream is initialized by
 114 .BR setspent ().
 115 When done reading, the program may call
 116 .BR endspent ()
 117 so that resources can be deallocated.
 118 .\" some systems require a call of setspent() before the first getspent()
 119 .\" glibc does not
 120 .LP
 121 The
 122 .BR fgetspent ()
 123 function is similar to
 124 .BR getspent ()
 125 but uses the supplied stream instead of the one implicitly opened by
 126 .BR setspent ().
 127 .LP
 128 The
 129 .BR sgetspent ()
 130 function parses the supplied string
 131 .I s
 132 into a struct
 133 .IR spwd .
 134 .LP
 135 The
 136 .BR putspent ()
 137 function writes the contents of the supplied struct
 138 .I spwd
 139 .I *p
 140 as a text line in the shadow password file format to the stream
 141 .IR fp .
 142 String entries with value NULL and numerical entries with value \-1
 143 are written as an empty string.
 144 .LP
 145 The
 146 .BR lckpwdf ()
 147 function is intended to protect against multiple simultaneous accesses
 148 of the shadow password database.
 149 It tries to acquire a lock, and returns 0 on success,
 150 or \-1 on failure (lock not obtained within 15 seconds).
 151 The
 152 .BR ulckpwdf ()
 153 function releases the lock again.
 154 Note that there is no protection against direct access of the shadow
 155 password file.
 156 Only programs that use
 157 .BR lckpwdf ()
 158 will notice the lock.
 159 .LP
 160 These were the functions that formed the original shadow API.
 161 They are widely available.
 162 .\" Also in libc5
 163 .\" SUN doesn't have sgetspent()
 164 .SS Reentrant versions
 165 Analogous to the reentrant functions for the password database, glibc
 166 also has reentrant functions for the shadow password database.
 167 The
 168 .BR getspnam_r ()
 169 function is like
 170 .BR getspnam ()
 171 but stores the retrieved shadow password structure in the space pointed to by
 172 .IR spbuf .
 173 This shadow password structure contains pointers to strings, and these strings
 174 are stored in the buffer
 175 .I buf
 176 of size
 177 .IR buflen .
 178 A pointer to the result (in case of success) or NULL (in case no entry
 179 was found or an error occurred) is stored in
 180 .IR *spbufp .
 181 .LP
 182 The functions
 183 .BR getspent_r (),
 184 .BR fgetspent_r (),
 185 and
 186 .BR sgetspent_r ()
 187 are similarly analogous to their nonreentrant counterparts.
 188 .LP
 189 Some non-glibc systems also have functions with these names,
 190 often with different prototypes.
 191 .\" SUN doesn't have sgetspent_r()
 192 .SS Structure
 193 The shadow password structure is defined in \fI<shadow.h>\fP as follows:
 194 .sp
 195 .in +4n
 196 .nf
 197 struct spwd {
 198     char *sp_namp;     /* Login name */
 199     char *sp_pwdp;     /* Encrypted password */
 200     long  sp_lstchg;   /* Date of last change
 201                           (measured in days since
 202                           1970-01-01 00:00:00 +0000 (UTC)) */
 203     long  sp_min;      /* Min # of days between changes */
 204     long  sp_max;      /* Max # of days between changes */
 205     long  sp_warn;     /* # of days before password expires
 206                           to warn user to change it */
 207     long  sp_inact;    /* # of days after password expires
 208                           until account is disabled */
 209     long  sp_expire;   /* Date when account expires
 210                           (measured in days since
 211                           1970-01-01 00:00:00 +0000 (UTC)) */
 212     unsigned long sp_flag;  /* Reserved */
 213 };
 214 .fi
 215 .in
 216 .SH RETURN VALUE
 217 The functions that return a pointer return NULL if no more entries
 218 are available or if an error occurs during processing.
 219 The functions which have \fIint\fP as the return value return 0 for
 220 success and \-1 for failure, with
 221 .I errno
 222 set to indicate the cause of the error.
 223 .LP
 224 For the nonreentrant functions, the return value may point to static area,
 225 and may be overwritten by subsequent calls to these functions.
 226 .LP
 227 The reentrant functions return zero on success.
 228 In case of error, an error number is returned.
 229 .SH ERRORS
 230 .TP
 231 .B EACCES
 232 The caller does not have permission to access the shadow password file.
 233 .TP
 234 .B ERANGE
 235 Supplied buffer is too small.
 236 .SH FILES
 237 .TP
 238 .I /etc/shadow
 239 local shadow password database file
 240 .TP
 241 .I /etc/.pwd.lock
 242 lock file
 243 .LP
 244 The include file
 245 .I <paths.h>
 246 defines the constant
 247 .B _PATH_SHADOW
 248 to the pathname of the shadow password file.
 249 .SH CONFORMING TO
 250 The shadow password database and its associated API are
 251 not specified in POSIX.1-2001.
 252 However, many other systems provide a similar API.
 253 .SH SEE ALSO
 254 .BR getgrnam (3),
 255 .BR getpwnam (3),
 256 .BR getpwnam_r (3),
 257 .BR shadow (5)
 258 .SH COLOPHON
 259 This page is part of release 3.64 of the Linux
 260 .I man-pages
 261 project.
 262 A description of the project,
 263 and information about reporting bugs,
 264 can be found at
 265 \%http://www.kernel.org/doc/man\-pages/.