# shadow

## NAME



           shadow, getspnam - encrypted password file routines
    


## SYNTAX



           _#include <shadow.h>_
    
           _struct spwd *getspent();_
    
           _struct spwd *getspnam(char *name);_
    
           _void setspent();_
    
           _void endspent();_
    
           _struct spwd *fgetspent(FILE *fp);_
    
           _struct spwd *sgetspent(char *cp);_
    
           _int putspent(struct spwd *p, FILE *fp);_
    
           _int lckpwdf();_
    
           _int ulckpwdf();_
    


## DESCRIPTION



           _shadow_ manipulates the contents of the shadow password file,
           /etc/shadow. The structure in the _#include_ file is:
    
               struct spwd {
                     char      *sp_namp; /* user login name */
                     char      *sp_pwdp; /* encrypted password */
                     long int       sp_lstchg; /* last password change */
                     long int       sp_min; /* days until change allowed. */
                     long int       sp_max; /* days before change required */
                     long int       sp_warn; /* days warning for expiration */
                     long int       sp_inact; /* days before account inactive */
                     long int       sp_expire; /* date when account expires */
                     unsigned long int   sp_flag; /* reserved for future use */
               }
    
           The meanings of each field are:
    
           •   sp_namp - pointer to null-terminated user name
    
           •   sp_pwdp - pointer to null-terminated password
    
           •   sp_lstchg - days since Jan 1, 1970 password was last changed
    
           •   sp_min - days before which password may not be changed
    
           •   sp_max - days after which password must be changed
    
           •   sp_warn - days before password is to expire that user is
               warned of pending password expiration
    
           •   sp_inact - days after password expires that account is
               considered inactive and disabled
    
           •   sp_expire - days since Jan 1, 1970 when account will be
               disabled
    
           •   sp_flag - reserved for future use
    


## DESCRIPTION



           _getspent_ , _getspname_ , _fgetspent_ , and _sgetspent_ each return a
           pointer to a _struct spwd_.  _getspent_ returns the next entry from
           the file, and _fgetspent_ returns the next entry from the given
           stream, which is assumed to be a file of the proper format.
           _sgetspent_ returns a pointer to a _struct spwd_ using the provided
           string as input.  _getspnam_ searches from the current position in
           the file for an entry matching _name_.
    
           _setspent_ and _endspent_ may be used to begin and end, respectively,
           access to the shadow password file.
    
           The _lckpwdf_ and _ulckpwdf_ routines should be used to insure
           exclusive access to the /etc/shadow file.  _lckpwdf_ attempts to
           acquire a lock using _pw_lock_ for up to 15 seconds. It continues by
           attempting to acquire a second lock using _spw_lock_ for the
           remainder of the initial 15 seconds. Should either attempt fail
           after a total of 15 seconds, _lckpwdf_ returns -1. When both locks
           are acquired 0 is returned.
    


## DIAGNOSTICS



           Routines return NULL if no more entries are available or if an
           error occurs during processing. Routines which have _int_ as the
           return value return 0 for success and -1 for failure.
    


## CAVEATS



           These routines may only be used by the superuser as access to the
           shadow password file is restricted.
    


## FILES



           /etc/shadow
               Secure user account information.
    


* * *