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