getprtcent(S)                  6 January 1993                  getprtcent(S)


 Name

    getprtcent, getprtcnam, setprtcent, endprtcent, putprtcnam - manipulate
    terminal control database entry

 Syntax


    cc  . . .  -lprot -lx


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

    struct pr_term *getprtcent ()

    struct pr_term *getprtcnam (name)
    char *name;

    void setprtcent ()

    void endprtcent ()

    int putprtcnam (name, pr)
    char *name;
    struct pr_term *pr;


 Description

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


       struct        pr_term  {
               struct t_field ufld;
               struct t_flag uflg;
               struct t_field sfld;
               struct t_flag sflg;
       };

       struct        t_field  {
               char        fd_devname[12]; /* Same size as utmp entry */
               ushort      fd_uid;         /* uid of last successful login */
               time_t      fd_slogin;      /* time stamp of   "        "   */
               ushort      fd_uuid;        /* uid of last unsuccessful login */
               time_t      fd_ulogin;      /* time stamp of  "           "   */
               ushort      fd_loutuid;     /* uid of last logout */
               time_t      fd_louttime;    /* time stamp of   "    */
               ushort      fd_nlogins;     /* consecutive failed attempts */
               ushort      fd_max_tries;   /* max unsuc login tries allowed */
               time_t      fd_logdelay;    /* delay between login tries */
               char        fd_label[AUTH_TLSIZ];/* terminal label */
               char        fd_lock;        /* terminal locked? */
               ushort      fd_login_timeout; /* login timeout in seconds */
       };

       struct        t_flag  {
               unsigned
                       fg_devname:1,        /* Is fd_devname set? */
                       fg_uid:1,            /* Is fd_uid set? */
                       fg_slogin:1,         /* Is fd_stime set? */
                       fg_uuid:1,           /* Is fd_uuid set? */
                       fg_ulogin:1,         /* Is fd_ftime set? */
                       fg_loutuid:1,        /* Is fd_loutuid set? */
                       fg_louttime:1,       /* Is fd_louttime set? */
                       fg_nlogins:1,        /* Is fd_nlogins set? */
                       fg_max_tries:1,      /* Is fd_max_tries set? */
                       fg_logdelay:1,       /* Is fd_logdelay set? */
                       fg_label:1,          /* Is fd_label set? */
                       fg_lock:1,           /* Is fd_lock set? */
                       fg_login_timeout:1;  /* Is fd_login_timeout valid? */
       };


    Because these structures are declared in <prot.h>, they need not be rede-
    clared.

    When the getprtcent routine is first called, it returns a pointer to the
    first user prterm structure in the database. Thereafter, it returns a
    pointer to the next prterm structure in the database. So, successive
    calls can be used to search the entire database.

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

    The setprtcent routine resets the file pointer to the beginning of the
    terminal control file to allow repeated searches.  The endprtcent routine
    closes the terminal control file when processing is complete.

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

 Return value

    Upon successful completion, the getprtcent and getprtcnam routines each
    returns a pointer to a prterm structure.  The putprtcnam 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 setprtcent or endprtcent 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 terminal 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/system/ttys

 See also

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

 Standards conformance

    endprtcent, getprtcent, getprtcnam, putprtcnam and setprtcent are not
    part of any currently supported standard; they are an extension of AT&T
    System V provided by the Santa Cruz Operation.