getspent(3C)                                                   getspent(3C)

NAME
     getspent, getspnam, lckpwdf, ulckpwdf, setspent, endspent, fgetspent -
     amend shadow password file entry

SYNOPSIS
     #include <shadow.h>

     struct spwd *getspent(void);

     struct spwd *getspnam(const char *name);

     int lckpwdf(void);

     int ulckpwdf(void);

     void setspent(void);

     void endspent(void);

     struct spwd *fgetspent(FILE *fp);

DESCRIPTION
     The getspent() and getspnam() routines each return a pointer to an
     object with the following structure containing the broken-out fields
     of a line in the /etc/shadow file. Each line in the file contains a
     "shadow password" structure, declared in the shadow.h header file:

        struct spwd{
              char    *spnamp;
              char    *sppwdp;
              long    splstchg;
              long    spmin;
              long    spmax;
              long    spwarn;
              long    spinact;
              long    spexpire;
              unsigned long   spflag;
        };

     The getspent() routine when first called returns a pointer to the
     first spwd structure in the file; thereafter, it returns a pointer to
     the next spwd structure in the file; so successive calls can be used
     to search the entire file. The getspnam() routine searches from the
     beginning of the file until a login name matching name is found, and
     returns a pointer to the particular structure in which it was found.
     The getspent() and getspnam() routines populate the spmin, spmax,
     splstchg, spwarn, spinact, spexpire, or spflag field with -1 if
     the corresponding field in /etc/shadow is empty. If end-of-file is
     reached, or if a reading or format error is encountered in the file,
     these functions return a null pointer and set errno to EINVAL.

     /etc/.pwd.lock is the lock file. It is used to coordinate modification



Page 1                       Reliant UNIX 5.44                Printed 11/98

getspent(3C)                                                   getspent(3C)

     access to the password files /etc/passwd and /etc/shadow. lckpwdf()
     and ulckpwdf() are routines that are used to gain modification access
     to the password files, through the lock file. A process first uses
     lckpwdf() to lock the lock file, thereby gaining exclusive rights to
     modify the /etc/passwd or /etc/shadow password file. Upon completing
     modifications, a process should release the lock on the lock file via
     ulckpwdf(). This mechanism prevents simultaneous modification of the
     password files.

     lckpwdf() attempts to lock the file /etc/.pwd.lock within 15 seconds.
     If unsuccessful, e.g., /etc/.pwd.lock is already locked, it returns
     -1. If successful, a return code other than -1 is returned.

     ulckpwdf() attempts to unlock the file /etc/.pwd.lock. If unsuccess-
     ful, e.g., /etc/.pwd.lock is already unlocked, it returns -1. If suc-
     cessful, it returns 0.

     A call to the setspent() routine has the effect of rewinding the sha-
     dow password file to allow repeated searches. The endspent() routine
     may be called to close the shadow password file when processing is
     complete.

     The fgetspent() routine returns a pointer to the next spwd structure
     in the stream fp, which matches the format of /etc/shadow.

RESULT
     getspent(), getspnam(), lckpwdf(), ulckpwdf(), and fgetspent() return
     a null pointer on end-of-file or error.

NOTES
     This routine is for internal use only; compatibility is not
     guaranteed.

     All information is contained in a static area, so it must be copied if
     it is to be saved.

FILES
     /etc/shadow

     /etc/passwd

     /etc/.pwd.lock

SEE ALSO
     getpwent(3C), putpwent(3C), putspent(3C).









Page 2                       Reliant UNIX 5.44                Printed 11/98