getspent(3C)            LIBRARY FUNCTIONS            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 *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



                                                                1

getspent(3C)            LIBRARY FUNCTIONS            getspent(3C)



     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  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.




                                                                2

getspent(3C)            LIBRARY FUNCTIONS            getspent(3C)























































                                                                3