getprfient(S)                  6 January 1993                  getprfient(S)


 Name

    getprfient, getprfinam, setprfient, endprfient, putprfinam - manipulate
    file control database entry

 Syntax


    cc  . . .  -lprot -lx


    #include <sys/types.h>
    #include <sys/security.h>
    #include <sys/audit.h>
    #include <prot.h>

    struct pr_file *getprfient ()

    struct pr_file *getprfinam (name)
    char *name;

    void setprfient ()

    void endprfient ()

    int putprfinam (name, pr)
    char *name;
    struct pr_file *pr;


 Description

    The getprfient and getprfinam routines both return a pointer to an object
    with the following structure containing the broken-out fields of a line
    in the file control database.  Only entries in the database dealing with
    users are scanned.  Each line in the database contains a prfile struc-
    ture, declared in the <prot.h> header file:

       struct  pr_file  {
               struct f_field ufld;
               struct f_flag uflg;
       };

       struct  f_field  {
               char    *fd_name;       /* Holds full path name */
               ushort  fd_uid;         /* uid of owner */
               ushort  fd_gid;         /* gid of group */
               ushort  fd_mode;        /* permissions */
               char    fd_type[2];     /* file type (one of r,b,c,d,f,s) */
               off_t   fd_size;        /* size in bytes */
               time_t  fd_mtime;       /* last time file noted as touched */
               time_t  fd_ctime;       /* last time inode noted as touched */
               long    fd_cksum;       /* checksum for file (see sum(C)) */
       };

       struct  f_flag  {
               unsigned
                       fg_name:1,      /* Is fd_name set? */
                       fg_uid:1,       /* Is fd_uid set? */
                       fg_gid:1,       /* Is fd_gid set? */
                       fg_mode:1,      /* Is fd_mode set? */
                       fg_type:1,      /* Is fd_type set? */
                       fg_size:1,      /* Is fd_size set? */
                       fg_mtime:1,     /* Is fd_mtime set? */
                       fg_ctime:1,     /* Is fd_ctime set? */
                       fg_cksum:1;     /* Is fd_cksum set? */
       };


    Because this structure is declared in <prot.h>, it need not be rede-
    clared.

    When the getprfient routine is first called, it returns a pointer to the
    first user prfile structure in the database. Thereafter, it returns a
    pointer to the next user prfile structure in the database. So, succes-
    sive calls can be used to search the entire database.

    The getprfinam routine searches from the beginning of the database file
    until a login name matching the argument name is found. getprfinam
    returns a pointer to the particular prfile structure in which the argu-
    ment name was found.

    The setprfient routine resets the file pointer to the beginning of the
    file control file to allow repeated searches.  The endprfient routine
    closes the file control file when processing is complete.

    The putprfinam routine puts a new or replaced file control entry pr with
    key name into the file control file.  If the uflg.fgname member is 0,
    the requested entry is deleted from the file control database.  The
    putprfinam routine locks the database for all update operations, and per-
    forms an endprfient after the update or failed attempt.

 Return value

    Upon successful completion, the getprfient and getprfinam routines each
    returns a pointer to a prfile structure.  The putprfinam routine returns
    a non-zero value on a successful substitution, deletion, or addition and
    a value of zero upon failure.  If an end-of-file or an error is encoun-
    tered on reading, these functions return a NULL pointer.  No errors are
    defined for the setprfient or endprfient routines.

 Diagnostics

    Use feof() to test if a null return value is caused by an end-of-file or
    from a syntax error in the file control file.  The feof macro is
    described in 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/auth/files

 See also

    authcap(F), authcap(S), getprdfent(S), getprpwent(S), getprtcent(S)

 Standards conformance

    endprfient, getprfient, getprfinam, putprfinam, and setprfient are not
    part of any currently supported standard; they are an extension of AT&T
    System V provided by the Santa Cruz Operation.