GETSPENT(3C-SVR4)   RISC/os Reference Manual    GETSPENT(3C-SVR4)



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 *sp_namp;
               char *sp_pwdp;
               long sp_lstchg;
               long sp_min;
               long sp_max;
               long sp_warn;
               long sp_inact;
               long sp_expire;
               unsigned long  sp_flag;
          };

     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 succes-
     sive 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 sp_min,
     sp_max, sp_lstchg, sp_warn, sp_inact, sp_expire, or sp_flag
     field with -1 if the corresponding field in /etc/shadow is
     empty. If an end-of-file or an error is encountered on read-
     ing, or there is a format error in the file, these functions



                        Printed 11/19/92                   Page 1

GETSPENT(3C-SVR4)   RISC/os Reference Manual    GETSPENT(3C-SVR4)



     return a null pointer and set errno to EINVAL.

     /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 complet-
     ing modifications, a process should release the lock on the
     lock file via ulckpwdf.  This mechanism prevents simultane-
     ous 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                 Printed 11/19/92