getspent(3C)                     UNIX System V                     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.




10/89                                                                    Page 1

getspent(3C)                     UNIX System V                     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.

      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 unsuccessful,
      e.g., /etc/.pwd.lock is already unlocked, it returns -1.  If successful,
      it returns 0.

      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                                                                    10/89