terminfo.tail

ncurses-5.4

.\" $Id: terminfo.tail,v 1.38 2003/01/05 22:47:05 tom Exp $
.\" Beginning of terminfo.tail file
.ps +1
.PP
.SS A Sample Entry
.PP
The following entry, describing an ANSI-standard terminal, is representative
of what a \fBterminfo\fR entry for a modern terminal typically looks like.
.PP
.nf
.in -2
.ta .3i
.ft CW
\s-2ansi|ansi/pc-term compatible with color,
        mc5i,
        colors#8, ncv#3, pairs#64,
        cub=\\E[%p1%dD, cud=\\E[%p1%dB, cuf=\\E[%p1%dC,
        cuu=\\E[%p1%dA, dch=\\E[%p1%dP, dl=\\E[%p1%dM,
        ech=\\E[%p1%dX, el1=\\E[1K, hpa=\\E[%p1%dG, ht=\\E[I,
        ich=\\E[%p1%d@, il=\\E[%p1%dL, indn=\\E[%p1%dS, .indn=\\E[%p1%dT,
        kbs=^H, kcbt=\\E[Z, kcub1=\\E[D, kcud1=\\E[B,
        kcuf1=\\E[C, kcuu1=\\E[A, kf1=\\E[M, kf10=\\E[V,
        kf11=\\E[W, kf12=\\E[X, kf2=\\E[N, kf3=\\E[O, kf4=\\E[P,
        kf5=\\E[Q, kf6=\\E[R, kf7=\\E[S, kf8=\\E[T, kf9=\\E[U,
        kich1=\\E[L, mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S,
        op=\\E[37;40m, rep=%p1%c\\E[%p2%{1}%-%db,
        rin=\\E[%p1%dT, s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B,
        s3ds=\\E+B, setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm,
        setb=\\E[4%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m,
        setf=\\E[3%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m,
        sgr=\\E[0;10%?%p1%t;7%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;%?%p6%t;1%;%?%p7%t;8%;%?%p8%t;11%;%?%p9%t;12%;m,
        sgr0=\\E[0;10m, tbc=\\E[2g, u6=\\E[%d;%dR, u7=\\E[6n,
        u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%p1%dd,\s+2
.in +2
.fi
.ft R
.PP
Entries may continue onto multiple lines by placing white space at
the beginning of each line except the first.
Comments may be included on lines beginning with ``#''.
Capabilities in
.I terminfo
are of three types:
Boolean capabilities which indicate that the terminal has
some particular feature, numeric capabilities giving the size of the terminal
or the size of particular delays, and string
capabilities, which give a sequence which can be used to perform particular
terminal operations.
.PP
.SS Types of Capabilities
.PP
All capabilities have names.
For instance, the fact that
ANSI-standard terminals have
.I "automatic margins"
(i.e., an automatic return and line-feed
when the end of a line is reached) is indicated by the capability \fBam\fR.
Hence the description of ansi includes \fBam\fR.
Numeric capabilities are followed by the character `#' and then a positive value.
Thus \fBcols\fR, which indicates the number of columns the terminal has,
gives the value `80' for ansi.
Values for numeric capabilities may be specified in decimal, octal or hexadecimal,
using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF).
.PP
Finally, string valued capabilities, such as \fBel\fR (clear to end of line
sequence) are given by the two-character code, an `=', and then a string
ending at the next following `,'.
.PP
A number of escape sequences are provided in the string valued capabilities
for easy encoding of characters there.
Both \fB\eE\fR and \fB\ee\fR
map to an \s-1ESCAPE\s0 character,
\fB^x\fR maps to a control-x for any appropriate x, and the sequences
\fB\en \el \er \et \eb \ef \es\fR give
a newline, line-feed, return, tab, backspace, form-feed, and space.
Other escapes include \fB\e^\fR for \fB^\fR,
\fB\e\e\fR for \fB\e\fR,
\fB\e\fR, for comma,
\fB\e:\fR for \fB:\fR,
and \fB\e0\fR for null.
(\fB\e0\fR will produce \e200, which does not terminate a string but behaves
as a null character on most terminals, providing CS7 is specified.
See stty(1).)
Finally, characters may be given as three octal digits after a \fB\e\fR.
.PP
A delay in milliseconds may appear anywhere in a string capability, enclosed in
$<..> brackets, as in \fBel\fP=\eEK$<5>, and padding characters are supplied by
.I tputs
to provide this delay.
The delay must be a number with at most one decimal
place of precision; it may be followed by suffixes `*' or '/' or both.
A `*'
indicates that the padding required is proportional to the number of lines
affected by the operation, and the amount given is the per-affected-unit
padding required.
(In the case of insert character, the factor is still the
number of
.IR lines
affected.)  Normally, padding is advisory if the device has the \fBxon\fR
capability; it is used for cost computation but does not trigger delays.
A `/'
suffix indicates that the padding is mandatory and forces a delay of the given
number of milliseconds even on devices for which \fBxon\fR is present to
indicate flow control.
.PP
Sometimes individual capabilities must be commented out.
To do this, put a period before the capability name.
For example, see the second
.B ind
in the example above.
.br
.ne 5
.PP
.SS Fetching Compiled Descriptions
.PP
If the environment variable TERMINFO is set, it is interpreted as the pathname
of a directory containing the compiled description you are working on.
Only
that directory is searched.
.PP
If TERMINFO is not set, the \fBncurses\fR version of the terminfo reader code
will instead look in the directory \fB$HOME/.terminfo\fR
for a compiled description.
If it fails to find one there, and the environment variable TERMINFO_DIRS is
set, it will interpret the contents of that variable as a list of colon-
separated directories to be searched (an empty entry is interpreted as a
command to search \fI\*d\fR).
If no description is found in any of the
TERMINFO_DIRS directories, the fetch fails.
.PP
If neither TERMINFO nor TERMINFO_DIRS is set, the last place tried will be the
system terminfo directory, \fI\*d\fR.
.PP
(Neither the \fB$HOME/.terminfo\fR lookups nor TERMINFO_DIRS extensions are
supported under stock System V terminfo/curses.)
.PP
.SS Preparing Descriptions
.PP
We now outline how to prepare descriptions of terminals.
The most effective way to prepare a terminal description is by imitating
the description of a similar terminal in
.I terminfo
and to build up a description gradually, using partial descriptions
with
.I vi
or some other screen-oriented program to check that they are correct.
Be aware that a very unusual terminal may expose deficiencies in
the ability of the
.I terminfo
file to describe it
or bugs in the screen-handling code of the test program.
.PP
To get the padding for insert line right (if the terminal manufacturer
did not document it) a severe test is to edit a large file at 9600 baud,
delete 16 or so lines from the middle of the screen, then hit the `u'
key several times quickly.
If the terminal messes up, more padding is usually needed.
A similar test can be used for insert character.
.PP
.SS Basic Capabilities
.PP
The number of columns on each line for the terminal is given by the
\fBcols\fR numeric capability.
If the terminal is a \s-1CRT\s0, then the
number of lines on the screen is given by the \fBlines\fR capability.
If the terminal wraps around to the beginning of the next line when
it reaches the right margin, then it should have the \fBam\fR capability.
If the terminal can clear its screen, leaving the cursor in the home
position, then this is given by the \fBclear\fR string capability.
If the terminal overstrikes
(rather than clearing a position when a character is struck over)
then it should have the \fBos\fR capability.
If the terminal is a printing terminal, with no soft copy unit,
give it both
.B hc
and
.BR os .
.RB ( os
applies to storage scope terminals, such as \s-1TEKTRONIX\s+1 4010
series, as well as hard copy and APL terminals.)
If there is a code to move the cursor to the left edge of the current
row, give this as
.BR cr .
(Normally this will be carriage return, control M.)
If there is a code to produce an audible signal (bell, beep, etc)
give this as
.BR bel .
.PP
If there is a code to move the cursor one position to the left
(such as backspace) that capability should be given as
.BR cub1 .
Similarly, codes to move to the right, up, and down should be
given as
.BR cuf1 ,
.BR cuu1 ,
and
.BR cud1 .
These local cursor motions should not alter the text they pass over,
for example, you would not normally use `\fBcuf1\fP=\ ' because the
space would erase the character moved over.
.PP
A very important point here is that the local cursor motions encoded
in
.I terminfo
are undefined at the left and top edges of a \s-1CRT\s0 terminal.
Programs should never attempt to backspace around the left edge,
unless
.B bw
is given,
and never attempt to go up locally off the top.
In order to scroll text up, a program will go to the bottom left corner
of the screen and send the
.B ind
(index) string.
.PP
To scroll text down, a program goes to the top left corner
of the screen and sends the
.B ri
(reverse index) string.
The strings
.B ind
and
.B ri
are undefined when not on their respective corners of the screen.
.PP
Parameterized versions of the scrolling sequences are
.B indn
and
.B rin
which have the same semantics as
.B ind
and
.B ri
except that they take one parameter, and scroll that many lines.
They are also undefined except at the appropriate edge of the screen.
.PP
The \fBam\fR capability tells whether the cursor sticks at the right
edge of the screen when text is output, but this does not necessarily
apply to a
.B cuf1
from the last column.
The only local motion which is defined from the left edge is if
.B bw
is given, then a
.B cub1
from the left edge will move to the right edge of the previous row.
If
.B bw
is not given, the effect is undefined.
This is useful for drawing a box around the edge of the screen, for example.
If the terminal has switch selectable automatic margins,
the
.I terminfo
file usually assumes that this is on; i.e., \fBam\fR.
If the terminal has a command which moves to the first column of the next
line, that command can be given as
.B nel
(newline).
It does not matter if the command clears the remainder of the current line,
so if the terminal has no
.B cr
and
.B lf
it may still be possible to craft a working
.B nel
out of one or both of them.
.PP
These capabilities suffice to describe hard-copy and \*(lqglass-tty\*(rq terminals.
Thus the model 33 teletype is described as
.PP
.DT
.nf
.ft CW
.in -7
	\s-133\||\|tty33\||\|tty\||\|model 33 teletype,
	bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
.in +7
.ft R
.PP
while the Lear Siegler \s-1ADM\-3\s0 is described as
.PP
.DT
.nf
.ft CW
.in -7
	\s-1adm3\||\|3\||\|lsi adm3,
	am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
	ind=^J, lines#24,\s+1
.in +7
.ft R
.fi
.PP
.SS Parameterized Strings
.PP
Cursor addressing and other strings requiring parameters
in the terminal are described by a
parameterized string capability, with
.IR printf (3S)
like escapes \fB%x\fR in it.
For example, to address the cursor, the
.B cup
capability is given, using two parameters:
the row and column to address to.
(Rows and columns are numbered from zero and refer to the
physical screen visible to the user, not to any unseen memory.)
If the terminal has memory relative cursor addressing,
that can be indicated by
.BR mrcup .
.PP
The parameter mechanism uses a stack and special \fB%\fP codes
to manipulate it.
Typically a sequence will push one of the
parameters onto the stack and then print it in some format.
Print (e.g., "%d") is a special case.
Other operations, including "%t" pop their operand from the stack.
It is noted that more complex operations are often necessary,
e.g., in the \fBsgr\fP string.
.PP
The \fB%\fR encodings have the following meanings:
.PP
.TP 5
\s-1%%
outputs `%'
.TP
%\fI[[\fP:\fI]flags][width[.precision]][\fPdoxXs\fI]\fP
as in \fBprintf\fP, flags are [-+#] and space
.TP
%c
print pop() like %c in \fBprintf\fP
.TP
%s
print pop() like %s in \fBprintf\fP
.TP
%p[1-9]
push \fIi\fP'th parameter
.TP
%P[a-z]
set dynamic variable [a-z] to pop()
.TP
%g[a-z]
get dynamic variable [a-z] and push it
.TP
%P[A-Z]
set static variable [a-z] to pop()
.TP
%g[A-Z]
get static variable [a-z] and push it
.IP
The terms "static" and "dynamic" are misleading.
Historically, these are simply two different sets of variables,
whose values are not reset between calls to \fBtparm\fP.
However, that fact is not documented in other implementations.
Relying on it will adversely impact portability to other implementations.
.TP
%'\fIc\fP'
char constant \fIc\fP
.TP
%{\fInn\fP}
integer constant \fInn\fP
.TP
%l
push strlen(pop)
.TP
%+ %- %* %/ %m
arithmetic (%m is mod): push(pop() op pop())
.TP
%& %| %^
bit operations: push(pop() op pop())
.TP
%= %> %<
logical operations: push(pop() op pop())
.TP
%A, %O
logical and & or operations (for conditionals)
.TP
%! %~
unary operations push(op pop())
.TP
%i
add 1 to first two parameters (for ANSI terminals)
.TP
%? \fIexpr\fP %t \fIthenpart\fP %e \fIelsepart\fP %;
if-then-else, %e \fIelsepart\fP is optional.
else-if's are possible a la Algol 68:
.br
%? c\d1\u %t b\d1\u %e c\d2\u %t b\d2\u %e c\d3\u %t b\d3\u %e c\d4\u %t b\d4\u %e %;
.br
c\di\u are conditions, b\di\u are bodies.
.PP
Binary operations are in postfix form with the operands in the usual order.
That is, to get x-5 one would use "%gx%{5}%-".
%P and %g variables are
persistent across escape-string evaluations.
.PP
Consider the HP2645, which, to get to row 3 and column 12, needs
to be sent \eE&a12c03Y padded for 6 milliseconds.
Note that the order
of the rows and columns is inverted here, and that the row and column
are printed as two digits.
Thus its \fBcup\fR capability is \*(lqcup=6\eE&%p2%2dc%p1%2dY\*(rq.
.PP
The Microterm \s-1ACT-IV\s0 needs the current row and column sent
preceded by a \fB^T\fR, with the row and column simply encoded in binary,
\*(lqcup=^T%p1%c%p2%c\*(rq.
Terminals which use \*(lq%c\*(rq need to be able to
backspace the cursor (\fBcub1\fR),
and to move the cursor up one line on the screen (\fBcuu1\fR).
This is necessary because it is not always safe to transmit \fB\en\fR
\fB^D\fR and \fB\er\fR, as the system may change or discard them.
(The library routines dealing with terminfo set tty modes so that
tabs are never expanded, so \et is safe to send.