290 lines
6.8 KiB
Groff
290 lines
6.8 KiB
Groff
.\" Copyright (c) 1980, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)termcap.3 8.2 (Berkeley) 12/11/93
|
|
.\"
|
|
.Dd December 11, 1993
|
|
.Dt TERMCAP 3
|
|
.Os BSD 4
|
|
.Sh NAME
|
|
.Nm tgetent ,
|
|
.Nm tgetnum ,
|
|
.Nm tgetflag ,
|
|
.Nm tgetstr ,
|
|
.Nm tgoto ,
|
|
.Nm tputs ,
|
|
.Nm tparm ,
|
|
.Nm _set_ospeed
|
|
.Nd terminal independent operation routines
|
|
.Sh SYNOPSIS
|
|
.Fd #include <termcap.h>
|
|
.Vt char PC;
|
|
.Vt char *BC;
|
|
.Vt char *UP;
|
|
.Vt short ospeed;
|
|
.Ft int
|
|
.Fn tgetent "char *bp" "const char *name"
|
|
.Ft int
|
|
.Fn tgetnum "const char *id"
|
|
.Ft int
|
|
.Fn tgetflag "const char *id"
|
|
.Ft char *
|
|
.Fn tgetstr "const char *id" "char **area"
|
|
.Ft char *
|
|
.Fn tgoto "const char *cm" "int destcol" "int destline"
|
|
.Ft void
|
|
.Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)"
|
|
.Ft char *
|
|
.Fn tparm "const char *cp" "..."
|
|
.Ft void
|
|
.Fn _set_ospeed "long speed"
|
|
.Sh DESCRIPTION
|
|
These functions extract and use capabilities from a terminal capability data
|
|
base, usually
|
|
.Pa /usr/share/misc/termcap ,
|
|
the format of which is described in
|
|
.Xr termcap 5 .
|
|
These are low level routines;
|
|
see
|
|
.Xr curses 3
|
|
for a higher level package.
|
|
.Pp
|
|
The
|
|
.Fn tgetent
|
|
function
|
|
extracts the entry for terminal
|
|
.Fa name
|
|
into the buffer at
|
|
.Fa bp .
|
|
The
|
|
.Fa bp
|
|
argument
|
|
should be a character buffer of size
|
|
1024 and must be retained through all subsequent calls to
|
|
.Fn tgetnum ,
|
|
.Fn tgetflag ,
|
|
and
|
|
.Fn tgetstr .
|
|
The
|
|
.Fn tgetent
|
|
function
|
|
returns \-1 if none of the
|
|
.Nm termcap
|
|
data base files could be opened,
|
|
0 if the terminal name given does not have an entry,
|
|
and 1 if all goes well.
|
|
It will look in the environment for a
|
|
.Ev TERMCAP
|
|
variable.
|
|
If found, and the value does not begin with a slash,
|
|
and the terminal type
|
|
.Fa name
|
|
is the same as the environment string
|
|
.Ev TERM ,
|
|
the
|
|
.Ev TERMCAP
|
|
string is used instead of reading a
|
|
.Nm termcap
|
|
file.
|
|
If it does begin with a slash, the string is used as a path name
|
|
of the
|
|
.Nm termcap
|
|
file to search.
|
|
If
|
|
.Ev TERMCAP
|
|
does not begin with a slash and
|
|
.Fa name
|
|
is different from
|
|
.Ev TERM ,
|
|
.Fn tgetent
|
|
searches the files
|
|
.Pa $HOME/.termcap
|
|
and
|
|
.Pa /usr/share/misc/termcap ,
|
|
in that order, unless the environment variable
|
|
.Ev TERMPATH
|
|
exists,
|
|
in which case it specifies a list of file pathnames
|
|
(separated by spaces or colons) to be searched instead.
|
|
Whenever multiple files are searched and a
|
|
.Sy tc
|
|
field occurs in the requested entry, the entry it names must be found
|
|
in the same file or one of the succeeding files.
|
|
This can speed up entry into programs that call
|
|
.Fn tgetent ,
|
|
as well as help debug new terminal descriptions
|
|
or make one for your terminal if you can't write the file
|
|
.Pa /usr/share/misc/termcap .
|
|
.Pp
|
|
The
|
|
.Fn tgetnum
|
|
function
|
|
gets the numeric value of capability
|
|
.Fa id ,
|
|
returning \-1 if it is not given for the terminal.
|
|
The
|
|
.Fn tgetflag
|
|
function
|
|
returns 1 if the specified capability is present in
|
|
the terminal's entry, 0 if it is not.
|
|
The
|
|
.Fn tgetstr
|
|
function
|
|
returns the string value of the capability
|
|
.Fa id ,
|
|
places it in the buffer at
|
|
.Fa area ,
|
|
and advances the
|
|
.Fa area
|
|
pointer.
|
|
It decodes the abbreviations for this field described in
|
|
.Xr termcap 5 ,
|
|
except for cursor addressing and padding information.
|
|
The
|
|
.Fn tgetstr
|
|
function
|
|
returns
|
|
.Dv NULL
|
|
if the capability was not found.
|
|
.Pp
|
|
The
|
|
.Fn tgoto
|
|
function
|
|
returns a cursor addressing string decoded from
|
|
.Fa cm
|
|
to go to column
|
|
.Fa destcol
|
|
in line
|
|
.Fa destline .
|
|
It uses the external variables
|
|
.Va UP
|
|
(from the
|
|
.Sy up
|
|
capability)
|
|
and
|
|
.Va BC
|
|
(if
|
|
.Sy bc
|
|
is given rather than
|
|
.Sy bs )
|
|
if necessary to avoid placing
|
|
.Sy \en ,
|
|
.Sy ^D
|
|
or
|
|
.Sy ^@
|
|
in
|
|
the returned string.
|
|
(Programs which call
|
|
.Fn tgoto
|
|
should be sure to turn off the
|
|
.Dv XTABS
|
|
bit(s),
|
|
since
|
|
.Fn tgoto
|
|
may now output a tab.
|
|
Note that programs using termcap should in general turn off
|
|
.Dv XTABS
|
|
anyway since some terminals use control-I for other functions,
|
|
such as nondestructive space.)
|
|
If a
|
|
.Sy %
|
|
sequence is given which is not understood, then
|
|
.Fn tgoto
|
|
returns
|
|
.Pq Dv OOPS .
|
|
.Pp
|
|
The
|
|
.Fn tputs
|
|
function
|
|
decodes the leading padding information of the string
|
|
.Fa cp ;
|
|
.Fa affcnt
|
|
gives the number of lines affected by the operation, or 1 if this is
|
|
not applicable,
|
|
.Fa outc
|
|
is a routine which is called with each character in turn.
|
|
The external variable
|
|
.Va ospeed
|
|
should contain the output speed of the terminal as encoded by
|
|
.Xr stty 3 .
|
|
The
|
|
.Fn _set_ospeed
|
|
functions converts any (not exactly matched only) numeric speed to
|
|
.Xr stty 3
|
|
encoded speed and set
|
|
.Va ospeed
|
|
variable.
|
|
The external variable
|
|
.Va PC
|
|
should contain a pad character to be used (from the
|
|
.SY pc
|
|
capability)
|
|
if a null
|
|
.Pq Sy ^@
|
|
is inappropriate.
|
|
.Pp
|
|
The
|
|
.Fn tparm
|
|
function
|
|
instantiates the string
|
|
.Fa cp
|
|
with given parameters.
|
|
A pointer is returned which points to
|
|
the result of
|
|
.Fa cp
|
|
with the parameters applied.
|
|
If a
|
|
.Sy %
|
|
sequence is given which is not understood, then
|
|
.Fn tparm
|
|
returns
|
|
.Pq Dv OOPS .
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/misc/termcap -compact
|
|
.It Pa /usr/lib/libtermcap.a
|
|
.Fl l Ar ltermcap
|
|
library (also known as
|
|
.Fl l Ar ltermlib )
|
|
.It Pa /usr/share/misc/termcap
|
|
standard terminal capability data base
|
|
.It Pa $HOME/.termcap
|
|
user's terminal capability data base
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ex 1 ,
|
|
.Xr curses 3 ,
|
|
.Xr termcap 5
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
functions appeared in
|
|
.Bx 4.0 .
|