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