manual/shadow/original/man3/shadow.3

   1 .\"$Id: shadow.3,v 1.7 2001/01/25 10:43:51 kloczek Exp $
   2 .\" Copyright 1989 - 1993, Julianne Frances Haugh
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of Julianne F. Haugh nor the names of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY JULIE HAUGH AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL JULIE HAUGH OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .TH SHADOW 3
  29 .SH NAME
  30 shadow \- encrypted password file routines
  31 .SH SYNTAX
  32 .B #include <shadow.h>
  33 .PP
  34 .B struct spwd *getspent();
  35 .PP
  36 .B struct spwd *getspnam(char
  37 .IB *name );
  38 .PP
  39 .B void setspent();
  40 .PP
  41 .B void endspent();
  42 .PP
  43 .B struct spwd *fgetspent(FILE
  44 .IB *fp );
  45 .PP
  46 .B struct spwd *sgetspent(char
  47 .IB *cp );
  48 .PP
  49 .B int putspent(struct spwd
  50 .I *p,
  51 .B FILE
  52 .IB *fp );
  53 .PP
  54 .B int lckpwdf();
  55 .PP
  56 .B int ulckpwdf();
  57 .SH DESCRIPTION
  58 .I shadow
  59 manipulates the contents of the shadow password file,
  60 \fI/etc/shadow\fR.
  61 The structure in the \fI#include\fR file is
  62 .sp
  63 struct spwd {
  64 .in +.5i
  65 .br
  66         char    *sp_namp; /* user login name */
  67 .br
  68         char    *sp_pwdp; /* encrypted password */
  69 .br
  70         long    sp_lstchg; /* last password change */
  71 .br
  72         int     sp_min; /* days until change allowed. */
  73 .br
  74         int     sp_max; /* days before change required */
  75 .br
  76         int     sp_warn; /* days warning for expiration */
  77 .br
  78         int     sp_inact; /* days before account inactive */
  79 .br
  80         int     sp_expire; /* date when account expires */
  81 .br
  82         int     sp_flag; /* reserved for future use */
  83 .br
  84 .in -.5i
  85 }
  86 .PP
  87 The meanings of each field are
  88 .sp
  89 sp_namp \- pointer to null-terminated user name.
  90 .br
  91 sp_pwdp \- pointer to null-terminated password.
  92 .br
  93 sp_lstchg \- days since Jan 1, 1970 password was last changed.
  94 .br
  95 sp_min \- days before which password may not be changed.
  96 .br
  97 sp_max \- days after which password must be changed.
  98 .br
  99 sp_warn \- days before password is to expire that user is warned
 100 of pending password expiration.
 101 .br
 102 sp_inact \- days after password expires that account is considered
 103 inactive and disabled.
 104 .br
 105 sp_expire \- days since Jan 1, 1970 when account will be disabled.
 106 .br
 107 sp_flag \- reserved for future use.
 108 .SH DESCRIPTION
 109 \fBgetspent\fR, \fBgetspname\fR, \fBfgetspent\fR, and \fBsgetspent\fR
 110 each return a pointer to a \fBstruct spwd\fR.
 111 \fBgetspent\fR returns the
 112 next entry from the file, and \fBfgetspent\fR returns the next
 113 entry from the given stream, which is assumed to be a file of
 114 the proper format.
 115 \fBsgetspent\fR returns a pointer to a \fBstruct spwd\fR using the
 116 provided string as input.
 117 \fBgetspnam\fR searches from the current position in the file for
 118 an entry matching \fBname\fR.
 119 .PP
 120 \fBsetspent\fR and \fBendspent\fR may be used to begin and end,
 121 respectively, access to the shadow password file.
 122 .PP
 123 The \fBlckpwdf\fR and \fBulckpwdf\fR routines should be used to
 124 insure exclusive access to the \fI/etc/shadow\fR file.
 125 \fBlckpwdf\fR attempts to acquire a lock using \fBpw_lock\fR for
 126 up to 15 seconds.
 127 It continues by attempting to acquire a second lock using \fBspw_lock\fR
 128 for the remainder of the initial 15 seconds.
 129 Should either attempt fail after a total of 15 seconds, \fBlckpwdf\fR
 130 returns -1.
 131 When both locks are acquired 0 is returned.
 132 .SH DIAGNOSTICS
 133 Routines return NULL if no more entries are available or if an
 134 error occurs during processing.
 135 Routines which have \fBint\fR as the return value return 0 for
 136 success and -1 for failure.
 137 .SH CAVEATS
 138 These routines may only be used by the super user as access to
 139 the shadow password file is restricted.
 140 .SH FILES
 141 /etc/shadow \- encrypted user passwords
 142 .SH SEE ALSO
 143 .BR getpwent (3),
 144 .BR shadow (5)
 145 .SH AUTHOR
 146 Julianne Frances Haugh (jockgrrl@ix.netcom.com)