getspent(S)                    6 January 1993                    getspent(S)


 Name

    getspent, getspnam, setspent, endspent, fgetspent, lckpwdf, ulckpwdf -
    get shadow password file entry

 Syntax


    #include <shadow.h>

    struct spwd *getspent (void)

    struct spwd *getspnam (name)
    char *name;

    int lckpwdf (void)

    int ulckpwdf (void)

    void setspent (void)

    void endspent (void)

    struct spwd *fgetspent (fp)
    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 pass-
    word'' 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;
       };


    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 log-
    in 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'' or ``sp_lstchg'' 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.

    /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 suc-
    cessful, 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

 Diagnostics

    A NULL pointer is returned on EOF or error.

 Notes

    If a program not otherwise using standard I/O uses this routine, the size
    of the program will increase more than might be expected.

    These routines are provided for compatibility purposes only, and may not
    function correctly on all systems.  We recommend that the getprpwent(S)
    routines be used as an alternative.

    All information is contained in a static area, so it must be copied if it
    is to be saved.

 See also

    putspent(S), getpwent(S), putpwent(S), getprpwent(S)

 Standards conformance

    The getspent, getspnam, setspent, endspent, fgetspent, lckpwdf, and
    ulckpwdf routines are conformant with AT&T SVID Issue 3.