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