getspent(3C)                                                   getspent(3C)


   NAME
         getspent, getspnam, setspent, endspent, fgetspent, lckpwdf, ulckpwdf
         - manipulate 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 an end-of-file or
         an error is encountered on reading, or there is a format error in the
         file, these functions return a NULL pointer and set errno to EINVAL.



   7/91                                                                 Page 1

   getspent(3C)                                                   getspent(3C)


         /etc/.pwd.lock is the lock file.  It is used to coordinate
         modification 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.

         The lckpwdf routine attempts to lock the file /etc/.pwd.lock.  If
         file /etc/.pwd.lock is already locked, lckpwdf tries for 15 seconds
         to lock the file.  If lckpwdf is unsuccessful, then lckpwdf returns a
         -1.  If lckpwdf succeeds to lock the file /etc/.pwd.lock within 15
         seconds, then a return code other than -1 is returned.

         The ulckpwdf routine attempts to unlock the file /etc/.pwd.lock.  If
         successful, ulckpwdf returns a 0.  If the unlocking failed, as in the
         case that file /etc/.pwd.lock was not locked initially, then ulckpwdf
         returns a -1.

         A call to the setspent routine has the effect of rewinding the shadow
         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.

   FILES
         /etc/shadow
         /etc/passwd
         /etc/.pwd.lock

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

   DIAGNOSTICS
         getspent, getspnam, lckpwdf, ulckpwdf, and fgetspent return a null
         pointer on EOF 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.






   Page 2                                                                 7/91