getpwent(S)                    6 January 1993                    getpwent(S)


 Name

    getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent - get
    password file entry

 Syntax


    cc  . . .  -lc


    #include <pwd.h>

    struct passwd *getpwent ()

    struct passwd *getpwuid (uid)
    int uid;

    struct passwd *getpwnam (name)
    char *name;

    void setpwent ()

    void endpwent ()

    struct passwd *fgetpwent (f)
    FILE *f;


 Description

    The getpwent, getpwuid, and getpwnam routines each returns a pointer to
    an object with a structure containing the broken-out fields of a line in
    the /etc/passwd file, a passwd structure declared in the <pwd.h> header
    file.  Refer to this header file for a listing of the passwd structure.
    Because the elements vary by the type of standards compliance that you
    are using, it is not included here.  Because this structure is in
    <pwd.h>, it does not need to be redeclared.  The meanings of the fields
    in the passwd structure are described in passwd(FP).

    When the getpwent routine is first called, it returns a pointer to the
    first passwd structure in the /etc/passwd file.  Thereafter, it returns a
    pointer to the next passwd structure in the file.  So successive calls to
    getpwent can be used to search the entire file.

    The getpwuid routine searches from the beginning of the /etc/passwd file
    until a numerical user ID matching the argument uid is found.  getpwuid
    returns a pointer to the particular passwd structure in which the argu-
    ment uid was found.

    Like getpwuid, the getpwnam routine searches from the beginning of the
    /etc/passwd file until a login name matching the argument name is found.
    getpwnam returns a pointer to the particular passwd structure in which
    the argument name was found.

    The setpwent routine resets the file pointer to the beginning of  the
    password file, /etc/passwd, to allow repeated searches.  The endpwent
    routine closes the password file, /etc/passwd, when processing is com-
    plete.

    The fgetpwent routine returns a pointer to the next passwd structure
    which matches the format of /etc/passwd in the stream argument f.

 Return value

    Upon successful completion, the routines getpwent, getpwuid, getpwnam,
    and fgetpwent each return a pointer to a passwd structure.  If an end-
    of-file or an error is encountered on reading, these routines return a
    NULL pointer.  No errors are defined for the setpwent or endpwent rou-
    tines.

 Diagnostics

    Use feof() to test if a null return value is caused by an end-of-file or
    from a syntax error in the password file.  The feof macro is described on
    the ferror(S) manual page.

 Note

    All information is contained in a static area, so it must be copied if it
    is to be saved.  Otherwise, it may be overwritten on subsequent calls to
    these routines.

 Files

    /etc/passwd

 See also

    feof(S), getlogin(S), getgrent(S), passwd(FP)

 Standards conformance

    endpwent, getpwent and setpwent conforms with:
    AT&T SVID Issue 2.

    getpwnam and getpwuid conforms with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.

    The fgetpwent routine has been withdrawn from XPG3.