getspent(3C)                   DG/UX R4.11MU05                  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 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 sp_min, sp_max,
       sp_lstchg, sp_warn, sp_inact, sp_expire field with -1 or the sp_flag
       field with 0 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.

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



   Considerations for Threads Programming
                     +----------+-----------------------------+
                     |          |                      async- |
                     |function  | reentrant   cancel   cancel |
                     |          |             point     safe  |
                     +----------+-----------------------------+
                     |endspent  |     Y         N        N    |
                     |fgetspent |     Y         N        N    |
                     |getspent  |     Y         N        N    |
                     |getspnam  |     Y         N        N    |
                     |lckpwdf   |     N         -        -    |
                     |setspent  |     Y         N        N    |
                     |ulckpwdf  |     N         -        -    |
                     +----------+-----------------------------+

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

SEE ALSO
       reentrant(3), 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.



Licensed material--property of copyright holder(s)