termcap(S)                     6 January 1993                     termcap(S)


 Name

    termcap: tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs - performs
    terminal functions

 Syntax


    extern char PC;
    extern char *BC;
    extern char *UP;
    extern short ospeed;

    int tgetent(bp, name)
    char *bp, *name;

    int tgetnum(id)
    char *id;

    int tgetflag(id)
    char *id;

    char * tgetstr(id, area)
    char *id, **area;

    char * tgoto(cm, destcol, destline)
    char *cm;
    int destcol, destline;

    void tputs(cp, affcnt, outc)
    char *cp;
    int affcnt;
    int (*outc)();


 Description

    These functions extract and use capabilities from the terminal capability
    data base termcap(F).  These are low level routines; see curses(S) for a
    higher level package.

    tgetent extracts the entry for terminal name into the buffer at bp; bp
    should be a character buffer of size 1024 and must be retained through
    all subsequent calls to tgetnum, tgetflag, and tgetstr.  tgetent returns
    -1 if it cannot open the termcap file, 0 if the terminal name given does
    not have an entry, and 1 if all goes well.  It looks in the environment
    for a TERMCAP variable.  If found, and the value does not begin with a
    slash, and the terminal type name is the same as the environment string
    TERM, the TERMCAP string is used instead of reading the termcap file.  If
    it does begin with a slash, the string is used as a pathname rather than
    /etc/termcap.  This can speed up entry into programs that call tgetent,
    as well as to help debug new terminal descriptions or to make one for
    your terminal if you can't write the file /etc/termcap.

    tgetnum gets the numeric value of capability id, returning -1 if it is
    not given for the terminal.  tgetflag returns 1 if the specified capabil-
    ity is present in the terminal's entry, 0 if it is not.  tgetstr returns
    the string value of capability id, advancing the area pointer.  It
    decodes the abbreviations for this field described in termcap(F), except
    for cursor addressing and padding information.

    tgoto returns a cursor addressing string decoded from cm to go to column
    destcol in line destline.  It uses the external variables UP (from the up
    capability) and BC (if bc is given rather than bs) if necessary to avoid
    placing \n, <Ctrl-D> or NULL in the returned string.  Programs which call
    tgoto should be sure to turn off the TAB3 bit (see tty(M)), since tgoto
    may now output a tab.  Note that programs using termcap should turn off
    TAB3 anyway since some terminals use <Ctrl-I> for other functions, such
    as nondestructive space.)  If a % sequence is given which is not under-
    stood, then tgoto returns OOPS.

    tputs decodes the leading padding information of the string cp; affcnt
    gives the number of lines affected by the operation, or 1 if this is not
    applicable, outc is a routine which is called with each character in
    turn.  The external variable ospeed should contain the output speed of
    the terminal as encoded by stty(C).  The external variable PC should con-
    tain a pad character to be used (from the pc capability) if a NULL is
    inappropriate.

 Files

    /usr/lib/libtermcap.a  -ltermcap library
    /etc/termcap           data base

 See also

    curses(S), termcap(F), tty(M)

 Notes

    These routines must be linked by using the -ltermcap linker option.

 Standards conformance

    termcap is not part of any currently supported standard; it was developed
    at the University of California at Berkeley and is used by permission.