.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.tail,v 1.122 2023/08/19 20:14:38 tom Exp $
+.\" $Id: terminfo.tail,v 1.148 2024/04/20 21:24:19 tom Exp $
.ps +1
-.SS User-Defined Capabilities
+.SS "User-Defined Capabilities"
.
The preceding section listed the \fIpredefined\fP capabilities.
They deal with some special features for terminals no longer
are awkward or impossible to represent by reusing the predefined
capabilities.
.PP
-\fBncurses\fP addresses this limitation by allowing user-defined capabilities.
+\fI\%ncurses\fP addresses this limitation by allowing user-defined
+capabilities.
The \fB@TIC@\fP and \fB@INFOCMP@\fP programs provide
the \fB\-x\fP option for this purpose.
When \fB\-x\fP is set,
\fB@TIC@\fP treats unknown capabilities as user-defined.
That is, if \fB@TIC@\fP encounters a capability name
which it does not recognize,
-it infers its type (boolean, number or string) from the syntax
+it infers its type (Boolean, number or string) from the syntax
and makes an extended table entry for that capability.
The \fBuse_extended_names\fP(3X) function makes this information
conditionally available to applications.
-The ncurses library provides the data leaving most of the behavior
-to applications:
+The \fI\%ncurses\fP library provides the data leaving most of the
+behavior to applications:
.bP
User-defined capability strings whose name begins
with \*(``k\*('' are treated as function keys.
.bP
-The types (boolean, number, string) determined by \fB@TIC@\fP
+The types (Boolean, number, string) determined by \fB@TIC@\fP
can be inferred by successful calls on \fBtigetflag\fP, etc.
.bP
If the capability name happens to be two characters,
terminfo implementations.
As a rule,
user-defined capabilities intended for use by termcap applications should
-be limited to booleans and numbers to avoid running past the 1023 byte
+be limited to Booleans and numbers to avoid running past the 1023 byte
limit assumed by termcap implementations and their applications.
In particular, providing extended sets of function keys (past the 60
numbered keys and the handful of special named keys) is best done using
the longer names available using terminfo.
.PP
-The ncurses library uses a few of these user-defined capabilities,
+The \fI\%ncurses\fP library uses a few of these user-defined
+capabilities,
as described in \fBuser_caps\fR(5).
Other user-defined capabilities (including function keys) are
described in the terminal database, in the section on
.I "NCURSES USER-DEFINABLE CAPABILITIES"
.
-.SS A Sample Entry
+.SS "A Sample Entry"
.
The following entry, describing an ANSI-standard terminal, is representative
of what a \fBterminfo\fP entry for a modern terminal typically looks like.
.PP
-.nf
-.ft CW
-\s-2ansi|ansi/pc-term compatible with color,
+.EX
+\s-2ansi|ansi/pc\-term compatible with color,
am, mc5i, mir, msgr,
colors#8, cols#80, it#8, lines#24, ncv#3, pairs#64,
- acsc=+\\020\\,\\021-\\030.^Y0\\333`\\004a\\261f\\370g\\361h\\260
- j\\331k\\277l\\332m\\300n\\305o~p\\304q\\304r\\304s_t\\303
- u\\264v\\301w\\302x\\263y\\363z\\362{\\343|\\330}\\234~\\376,
- bel=^G, blink=\\E[5m, bold=\\E[1m, cbt=\\E[Z, clear=\\E[H\\E[J,
- cr=^M, cub=\\E[%p1%dD, cub1=\\E[D, cud=\\E[%p1%dB, cud1=\\E[B,
- cuf=\\E[%p1%dC, cuf1=\\E[C, cup=\\E[%i%p1%d;%p2%dH,
- cuu=\\E[%p1%dA, cuu1=\\E[A, dch=\\E[%p1%dP, dch1=\\E[P,
- dl=\\E[%p1%dM, dl1=\\E[M, ech=\\E[%p1%dX, ed=\\E[J, el=\\E[K,
- el1=\\E[1K, home=\\E[H, hpa=\\E[%i%p1%dG, ht=\\E[I, hts=\\EH,
- ich=\\E[%p1%d@, il=\\E[%p1%dL, il1=\\E[L, ind=^J,
- indn=\\E[%p1%dS, invis=\\E[8m, kbs=^H, kcbt=\\E[Z, kcub1=\\E[D,
- kcud1=\\E[B, kcuf1=\\E[C, kcuu1=\\E[A, khome=\\E[H, kich1=\\E[L,
- mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, op=\\E[39;49m,
- rep=%p1%c\\E[%p2%{1}%-%db, rev=\\E[7m, rin=\\E[%p1%dT,
- rmacs=\\E[10m, rmpch=\\E[10m, rmso=\\E[m, rmul=\\E[m,
- s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, s3ds=\\E+B,
- setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm,
- sgr=\\E[0;10%?%p1%t;7%;
+ acsc=+\e020\e,\e021\-\e030.\*^Y0\e333\(ga\e004a\e261f\e370g\e361h\e260
+ j\e331k\e277l\e332m\e300n\e305o\*~p\e304q\e304r\e304s_t\e303
+ u\e264v\e301w\e302x\e263y\e363z\e362{\e343|\e330}\e234\*~\e376,
+ bel=\*^G, blink=\eE[5m, bold=\eE[1m, cbt=\eE[Z, clear=\eE[H\eE[J,
+ cr=\*^M, cub=\eE[%p1%dD, cub1=\eE[D, cud=\eE[%p1%dB, cud1=\eE[B,
+ cuf=\eE[%p1%dC, cuf1=\eE[C, cup=\eE[%i%p1%d;%p2%dH,
+ cuu=\eE[%p1%dA, cuu1=\eE[A, dch=\eE[%p1%dP, dch1=\eE[P,
+ dl=\eE[%p1%dM, dl1=\eE[M, ech=\eE[%p1%dX, ed=\eE[J, el=\eE[K,
+ el1=\eE[1K, home=\eE[H, hpa=\eE[%i%p1%dG, ht=\eE[I, hts=\eEH,
+ ich=\eE[%p1%d@, il=\eE[%p1%dL, il1=\eE[L, ind=\*^J,
+ indn=\eE[%p1%dS, invis=\eE[8m, kbs=\*^H, kcbt=\eE[Z, kcub1=\eE[D,
+ kcud1=\eE[B, kcuf1=\eE[C, kcuu1=\eE[A, khome=\eE[H, kich1=\eE[L,
+ mc4=\eE[4i, mc5=\eE[5i, nel=\er\eE[S, op=\eE[39;49m,
+ rep=%p1%c\eE[%p2%{1}%\-%db, rev=\eE[7m, rin=\eE[%p1%dT,
+ rmacs=\eE[10m, rmpch=\eE[10m, rmso=\eE[m, rmul=\eE[m,
+ s0ds=\eE(B, s1ds=\eE)B, s2ds=\eE*B, s3ds=\eE+B,
+ setab=\eE[4%p1%dm, setaf=\eE[3%p1%dm,
+ sgr=\eE[0;10%?%p1%t;7%;
%?%p2%t;4%;
%?%p3%t;7%;
%?%p4%t;5%;
%?%p6%t;1%;
%?%p7%t;8%;
%?%p9%t;11%;m,
- sgr0=\\E[0;10m, smacs=\\E[11m, smpch=\\E[11m, smso=\\E[7m,
- smul=\\E[4m, tbc=\\E[3g, u6=\\E[%i%d;%dR, u7=\\E[6n,
- u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%i%p1%dd,
-.fi
-.ft R
+ sgr0=\eE[0;10m, smacs=\eE[11m, smpch=\eE[11m, smso=\eE[7m,
+ smul=\eE[4m, tbc=\eE[3g, u6=\eE[%i%d;%dR, u7=\eE[6n,
+ u8=\eE[?%[;0123456789]c, u9=\eE[c, vpa=\eE[%i%p1%dd,
+.EE
.PP
Entries may continue onto multiple lines by placing white space at
the beginning of each line except the first.
string
capabilities, which give a sequence which can be used to perform particular
terminal operations.
-.SS Types of Capabilities
+.SS "Types of Capabilities"
All capabilities have names.
For instance, the fact that
ANSI-standard terminals have
Both \fB\eE\fP and \fB\ee\fP
map to an \s-1ESCAPE\s0 character,
.bP
-\fB^x\fP maps to a control-x for any appropriate \fIx\fP, and
+\fB\*^\f(BIx\fR maps to a control-\fIx\fP for any appropriate \fIx\fP,
+and
.bP
the sequences
.RS 6
.PP
X/Open Curses does not say what \*(``appropriate \fIx\fP\*('' might be.
In practice, that is a printable ASCII graphic character.
-The special case \*(``^?\*('' is interpreted as DEL (127).
+The special case \*(``\*^?\*('' is interpreted as DEL (127).
In all other cases, the character value is AND'd with 0x1f,
mapping to ASCII control codes in the range 0 through 31.
.PP
Other escapes include
.bP
-\fB\e^\fP for \fB^\fP,
+\fB\e\*^\fP for \fB\*^\fP,
.bP
\fB\e\e\fP for \fB\e\fP,
.bP
in the example above.
.br
.ne 5
-.SS Fetching Compiled Descriptions
-The \fBncurses\fP library searches for terminal descriptions in several places.
-It uses only the first description found.
-The library has a compiled-in list of places to search
+.SS "Fetching Compiled Descriptions"
+Terminal descriptions in \fI\%ncurses\fP are stored in terminal
+databases.
+These databases, which are found by their pathname,
+may be configured either as directory trees or hashed databases
+(see \fBterm\fR(5)),
+.PP
+The library uses a compiled-in list of pathnames,
which can be overridden by environment variables.
Before starting to search,
-\fBncurses\fP eliminates duplicates in its search list.
+\fI\%ncurses\fP checks the search list,
+eliminating duplicates and pathnames where no terminal database is found.
+The \fI\%ncurses\fP library reads the first description
+which passes its consistency checks.
.bP
-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.
+The environment variable \fBTERMINFO\fR is checked first, for
+a terminal database containing the terminal description.
.bP
-If TERMINFO is not set,
-\fBncurses\fP will instead look in the directory \fB$HOME/.terminfo\fP
+Next,
+\fI\%ncurses\fP looks in \fI$HOME/.terminfo\fP
for a compiled description.
+.IP
+This is an optional feature which may be omitted entirely from
+the library, or limited to prevent accidental use by privileged applications.
.bP
-Next, if the environment variable TERMINFO_DIRS is set,
-\fBncurses\fP will interpret the contents of that variable
-as a list of colon-separated directories (or database files) to be searched.
+Next,
+if the environment variable \fI\%TERMINFO_DIRS\fP is set,
+\fI\%ncurses\fP interprets the contents of that variable
+as a list of colon-separated pathnames of terminal databases to be searched.
.IP
-An empty directory name (i.e., if the variable begins or ends
+An empty pathname (i.e., if the variable begins or ends
with a colon, or contains adjacent colons)
is interpreted as the system location \fI\*d\fP.
.bP
-Finally, \fBncurses\fP searches these compiled-in locations:
+Finally, \fI\%ncurses\fP searches these compiled-in locations:
.RS
.bP
a list of directories (@TERMINFO_DIRS@), and
.bP
-the system terminfo directory, \fI\*d\fP (the compiled-in default).
+the system terminfo directory, \fI\*d\fP
.RE
-.SS Preparing Descriptions
+.PP
+The \fBTERMINFO\fP variable can contain a terminal description instead
+of the pathname of a terminal database.
+If this variable begins with \*(``hex:\*('' or \*(``b64:\*(''
+then \fI\%ncurses\fP reads a terminal description from
+hexadecimal- or base64-encoded data,
+and if that description matches the name sought, will use that.
+This encoded data can be set using the \*(``\-Q\*('' option of
+\fB@TIC@\fR or \fB@INFOCMP@\fR.
+.PP
+The preceding addresses the usual configuration of \fI\%ncurses\fP,
+which uses terminal descriptions prepared in \fIterminfo\fP format.
+While \fItermcap\fP is less expressive,
+\fI\%ncurses\fP can also be configured to read \fItermcap\fP
+descriptions.
+In that configuration,
+it checks the \fI\%TERMCAP\fP and \fI\%TERMPATH\fP variables
+(for content and search path,
+respectively)
+after the system terminal database.
+.SS "Preparing Descriptions"
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
key several times quickly.
If the terminal messes up, more padding is usually needed.
A similar test can be used for insert character.
-.SS Basic Capabilities
+.SS "Basic Capabilities"
The number of columns on each line for the terminal is given by the
\fBcols\fP numeric capability.
If the terminal is a \s-1CRT\s0, then the
hard-copy and \*(``glass-tty\*('' terminals.
Thus the model 33 teletype is described as
.PP
-.DT
-.nf
-.ft CW
+.EX
.\".in -2
\s-133\||\|tty33\||\|tty\||\|model 33 teletype,
- bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
+ bel=\*^G, cols#72, cr=\*^M, cud1=\*^J, hc, ind=\*^J, os,\s+1
.\".in +2
-.ft R
-.fi
+.EE
.PP
while the Lear Siegler \s-1ADM-3\s0 is described as
.PP
-.DT
-.nf
-.ft CW
+.EX
.\".in -2
\s-1adm3\||\|3\||\|lsi adm3,
- am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
- ind=^J, lines#24,\s+1
+ am, bel=\*^G, clear=\*^Z, cols#80, cr=\*^M, cub1=\*^H, cud1=\*^J,
+ ind=\*^J, lines#24,\s+1
.\".in +2
-.ft R
-.fi
-.SS Parameterized Strings
+.EE
+.SS "Parameterized Strings"
Cursor addressing and other strings requiring parameters
in the terminal are described by a
parameterized string capability,
Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag,
avoiding interpreting \*(``%\-\*('' as an operator.
.TP
-\f(CW%c\fP
+\fB%c\fP
print \fIpop()\fP like %c in \fBprintf\fP
.TP
\fB%s\fP
an uninitialized local array on the stack in the \fBtparm\fP function.
.bP
SVr3.2 curses supported \fIstatic\fP variables.
-Those are an array in the \fBTERMINAL\fP
+Those are an array in the \fI\%TERMINAL\fP
structure (declared in \fBterm.h\fP),
and are zeroed automatically when the \fBsetupterm\fP function
allocates the data.
They are the same.
Like SVr4 curses, XPG4 curses does not initialize these explicitly.
.bP
-Before version 6.3, ncurses stores both \fIdynamic\fP and \fIstatic\fP
+Before version 6.3,
+\fI\%ncurses\fP stores both \fIdynamic\fP and \fIstatic\fP
variables in persistent storage, initialized to zeros.
.bP
-Beginning with version 6.3, ncurses stores \fIstatic\fP and \fIdynamic\fP
+Beginning with version 6.3,
+\fI\%ncurses\fP stores \fIstatic\fP and \fIdynamic\fP
variables in the same manner as SVr4.
.RS
.bP
-Unlike other implementations, ncurses zeros dynamic variables
+Unlike other implementations, \fI\%ncurses\fP zeros dynamic variables
before the first \fB%g\fP or \fB%P\fP operator.
.bP
Like SVr2,
-the scope of dynamic variables in ncurses
+the scope of dynamic variables in \fI\%ncurses\fP
is within the current call to
\fBtparm\fP.
Use static variables if persistent storage is needed.
.RE
.RE
.TP
-\fB%\(aq\fIc\fB\(aq\fR
+\fB%\*'\fIc\fB\*'\fR
char constant \fIc\fP
.TP
\fB%{\fInn\fB}\fR
\fB%+\fP, \fB%\-\fP, \fB%*\fP, \fB%/\fP, \fB%m\fP
arithmetic (%m is \fImod\fP): \fIpush(pop() op pop())\fP
.TP
-\fB%&\fP, \fB%|\fP, \fB%^\fP
+\fB%&\fP, \fB%|\fP, \fB%\*^\fP
bit operations (AND, OR and exclusive-OR): \fIpush(pop() op pop())\fP
.TP
\fB%=\fP, \fB%>\fP, \fB%<\fP
\fB%A\fP, \fB%O\fP
logical AND and OR operations (for conditionals)
.TP
-\fB%!\fP, \fB%~\fP
+\fB%!\fP, \fB%\*~\fP
unary operations (logical and bit complement): \fIpush(op pop())\fP
.TP
\fB%i\fP
.RE
.PP
The Microterm \s-1ACT-IV\s0 needs the current row and column sent
-preceded by a \fB^T\fP, with the row and column simply encoded in binary,
+preceded by a \fB\*^T\fP, with the row and column simply encoded in binary,
.RS
-cup=^T%p1%c%p2%c
+cup=\*^T%p1%c%p2%c
.RE
.PP
Terminals which use \*(``%c\*('' need to be able to
backspace the cursor (\fBcub1\fP),
and to move the cursor up one line on the screen (\fBcuu1\fP).
This is necessary because it is not always safe to transmit \fB\en\fP
-\fB^D\fP and \fB\er\fP, as the system may change or discard them.
+\fB\*^D\fP and \fB\er\fP, 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.
This turns out to be essential for the Ann Arbor 4080.)
A final example is the \s-1LSI ADM\s0-3a, which uses row and column
offset by a blank character, thus
.RS
-cup=\eE=%p1%\(aq \(aq%+%c%p2%\(aq \(aq%+%c
+cup=\eE=%p1%\*' \*'%+%c%p2%\*' \*'%+%c
.RE
.PP
After sending \*(``\eE=\*('', this pushes the first parameter, pushes the
in place of the two previous values) and outputs that value as a character.
Then the same is done for the second parameter.
More complex arithmetic is possible using the stack.
-.SS Cursor Motions
+.SS "Cursor Motions"
If the terminal has a fast way to home the cursor
(to very upper left corner of screen) then this can be given as
\fBhome\fP; similarly a fast way of getting to the lower left-hand corner
right edge of the display (rather than leaving the margin unmodified).
.PP
These are the margin-related capabilities:
+.PP
.TS
center;
-l l
-_ _
-lw8 lw18.
-\fBName Description\fP
+lb lb
+lb l .
+Name Description
+_
smgl Set left margin at current column
smgr Set right margin at current column
smgb Set bottom margin at current line
The \fBmgc\fP string capability should be defined.
Applications such as \fBtabs\fP(1) rely upon this to reset all margins.
.\"
-.SS Area Clears
+.SS "Area Clears"
If the terminal can clear from the current position to the end of the
line, leaving the cursor where it is, this should be given as \fBel\fP.
If the terminal can clear from the beginning of the line to the current
.B ed
is not available.)
.\"
-.SS Insert/delete line and vertical motions
+.SS "Insert/Delete Line and Vertical Motions"
If the terminal can open a new blank line before the line where the cursor
is, this should be given as \fBil1\fP; this is done only from the first
position of a line.
.B rc
(save and restore cursor) commands may be useful for ensuring that
your synthesized insert/delete string does not move the cursor.
-(Note that the \fBncurses\fP(3X) library does this synthesis
+(Note that the \fB\%ncurses\fP(3X) library does this synthesis
automatically, so you need not compose insert/delete strings for
an entry with \fBcsr\fP).
.PP
Yet another way to construct insert and delete might be to use a combination of
-index with the memory-lock feature found on some terminals (like the HP\-700/90
+index with the memory-lock feature found on some terminals (like the HP-700/90
series, which however also has insert/delete).
.PP
Inserting lines at the top or bottom of the screen can also be
on many terminals without a true insert/delete line,
and is often faster even on terminals with those features.
.PP
-The boolean \fBnon_dest_scroll_region\fP should be set if each scrolling
+The Boolean \fBnon_dest_scroll_region\fP should be set if each scrolling
window is effectively a view port on a screen-sized canvas.
To test for
this capability, create a scrolling region in the middle of the screen,
If the data scrolled
off the bottom of the region by the \fBri\fP re-appears, then scrolling
is non-destructive.
-System V and XSI Curses expect that \fBind\fP, \fBri\fP,
+System V and X/Open Curses expect that \fBind\fP, \fBri\fP,
\fBindn\fP, and \fBrin\fP will simulate destructive scrolling; their
documentation cautions you not to define \fBcsr\fP unless this is true.
This \fBcurses\fP implementation is more liberal and will do explicit erases
These indicate
that deleting a line or scrolling may bring non-blank lines up from below
or that scrolling back with \fBri\fP may bring down non-blank lines.
-.SS Insert/Delete Character
+.SS "Insert/Delete Character"
There are two basic kinds of intelligent terminals with respect to
insert/delete character which can be described using
-.I terminfo.
+.IR terminfo .
The most common insert/delete character operations affect only the characters
on the current line and shift characters off the end of the line rigidly.
Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make
with one parameter,
.IR n ,
to delete
-.I n characters,
+.IR n "characters,"
and delete mode by giving \fBsmdc\fP and \fBrmdc\fP
to enter and exit delete mode (any mode the terminal needs to be placed
in for
.PP
.TS
center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBtparm parameter attribute escape sequence\fP
-
-none none \\E[0m
-p1 standout \\E[0;1;7m
-p2 underline \\E[0;4m
-p3 reverse \\E[0;7m
-p4 blink \\E[0;5m
+lb lb lb
+l l l .
+tparm Parameter Attribute Escape Sequence
+_
+none none \eE[0m
+p1 standout \eE[0;1;7m
+p2 underline \eE[0;4m
+p3 reverse \eE[0;7m
+p4 blink \eE[0;5m
p5 dim not available
-p6 bold \\E[0;1m
-p7 invis \\E[0;8m
+p6 bold \eE[0;1m
+p7 invis \eE[0;8m
p8 protect not used
-p9 altcharset ^O (off) ^N (on)
+p9 altcharset \*^O (off) \*^N (on)
.TE
.PP
We begin each escape sequence by turning off any existing modes, since
The vt220 terminal has a protect mode,
though it is not commonly used in sgr
because it protects characters on the screen from the host's erasures.
-The altcharset mode also is different in that it is either ^O or ^N,
+The altcharset mode also is different in that it is either \*^O or \*^N,
depending on whether it is off or on.
-If all modes are turned on, the resulting sequence is \\E[0;1;4;5;7;8m^N.
+If all modes are turned on, the resulting sequence is \eE[0;1;4;5;7;8m\*^N.
.PP
Some sequences are common to different modes.
For example, ;7 is output when either p1 or p3 is true, that is, if
.ne 11
.TS
center;
-l l l
-l l l
-lw18 lw14 lw18.
-\fBsequence when to output terminfo translation\fP
-
-.ft CW
-\\E[0 always \\E[0
+lb lb lb
+l l l .
+Sequence When to Output terminfo Translation
+_
+\eE[0 always \eE[0
;1 if p1 or p6 %?%p1%p6%|%t;1%;
;4 if p2 %?%p2%|%t;4%;
;5 if p4 %?%p4%|%t;5%;
;7 if p1 or p3 %?%p1%p3%|%t;7%;
;8 if p7 %?%p7%|%t;8%;
m always m
-^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%;
-.ft R
+\*^N or \*^O if p9 \*^N, else \*^O %?%p9%t\*^N%e\*^O%;
.TE
.PP
Putting this all together into the sgr sequence gives:
.PP
-.ft CW
-.nf
- sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%;
- %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;,
-.fi
-.ft R
+.EX
+ sgr=\eE[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%;
+ %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\e016%e\e017%;,
+.EE
.PP
Remember that if you specify sgr, you must also specify sgr0.
Also, some implementations rely on sgr being given if sgr0 is,
specify the capability \fBos\fP.
If overstrikes are erasable with a blank,
then this should be indicated by giving \fBeo\fP.
-.SS Keypad and Function Keys
+.SS "Keypad and Function Keys"
If the terminal has a keypad that transmits codes when the keys are pressed,
this information can be given.
Note that it is not possible to handle
give them in \fBsmln\fP and \fBrmln\fP.
\fBsmln\fP is normally output after one or more pln
sequences to make sure that the change becomes visible.
-.SS Tabs and Initialization
+.SS "Tabs and Initialization"
A few capabilities are used only for tabs:
.bP
If the terminal has hardware tabs, the command to advance to the next
\fBhts\fP (\fBset_tab\fP) capabilities directly
only when the \fBit\fP (\fBinit_tabs\fP) capability
is set to a value other than \fIeight\fP.
-.SS Delays and Padding
+.SS "Delays and Padding"
Many older and slower terminals do not support either XON/XOFF or DTR
handshaking, including hard copy terminals and some very archaic CRTs
(including, for example, DEC VT100s).
after certain cursor motions and screen changes.
.PP
If the terminal uses xon/xoff handshaking for flow control (that is,
-it automatically emits ^S back to the host when its input buffers are
+it automatically emits \*^S back to the host when its input buffers are
close to full), set
.BR xon .
This capability suppresses the emission of padding.
Only the first character of the
.B pad
string is used.
-.SS Status Lines
+.SS "Status Lines"
Some terminals have an extra \*(``status line\*('' which is not normally used by
software (and thus not counted in the terminal's \fBlines\fP capability).
.PP
.PP
A command to erase or blank the status line may be specified as \fBdsl\fP.
.PP
-The boolean capability \fBeslok\fP specifies that escape sequences, tabs,
+The Boolean capability \fBeslok\fP specifies that escape sequences, tabs,
etc., work ordinarily in the status line.
.PP
-The \fBncurses\fP implementation does not yet use any of these capabilities.
+The \fI\%ncurses\fP implementation does not yet use any of these
+capabilities.
They are documented here in case they ever become important.
-.SS Line Graphics
+.SS "Line Graphics"
Many terminals have alternate character sets useful for forms-drawing.
Terminfo and \fBcurses\fP have built-in support
for most of the drawing characters
supported by the VT100, with some characters from the AT&T 4410v1 added.
This alternate character set may be specified by the \fBacsc\fP capability.
.PP
-.TS H
-center expand;
-l l l l l
-l l l l l
-_ _ _ _ _
-lw25 lw10 lw6 lw6 lw6.
-.\".TH
-\fBGlyph ACS Ascii acsc acsc\fP
-\fBName Name Default Char Value\fP
-arrow pointing right ACS_RARROW > + 0x2b
-arrow pointing left ACS_LARROW < , 0x2c
-arrow pointing up ACS_UARROW ^ \- 0x2d
-arrow pointing down ACS_DARROW v . 0x2e
-solid square block ACS_BLOCK # 0 0x30
-diamond ACS_DIAMOND + ` 0x60
-checker board (stipple) ACS_CKBOARD : a 0x61
-degree symbol ACS_DEGREE \e f 0x66
-plus/minus ACS_PLMINUS # g 0x67
-board of squares ACS_BOARD # h 0x68
-lantern symbol ACS_LANTERN # i 0x69
-lower right corner ACS_LRCORNER + j 0x6a
-upper right corner ACS_URCORNER + k 0x6b
-upper left corner ACS_ULCORNER + l 0x6c
-lower left corner ACS_LLCORNER + m 0x6d
-large plus or crossover ACS_PLUS + n 0x6e
-scan line 1 ACS_S1 ~ o 0x6f
-scan line 3 ACS_S3 \- p 0x70
-horizontal line ACS_HLINE \- q 0x71
-scan line 7 ACS_S7 \- r 0x72
-scan line 9 ACS_S9 \&_ s 0x73
-tee pointing right ACS_LTEE + t 0x74
-tee pointing left ACS_RTEE + u 0x75
-tee pointing up ACS_BTEE + v 0x76
-tee pointing down ACS_TTEE + w 0x77
-vertical line ACS_VLINE | x 0x78
-less-than-or-equal-to ACS_LEQUAL < y 0x79
-greater-than-or-equal-to ACS_GEQUAL > z 0x7a
-greek pi ACS_PI * { 0x7b
-not-equal ACS_NEQUAL ! | 0x7c
-UK pound sign ACS_STERLING f } 0x7d
-bullet ACS_BULLET o ~ 0x7e
+.TS
+center;
+Lb Cb S L Lb
+Lb2 Lb2 Lb Lb1 S
+Lb L C Lb Lx.
+\& acsc \& \&
+ACS Name Value Symbol ASCII Fallback / Glyph Name
+_
+ACS_RARROW 0x2b + > arrow pointing right
+ACS_LARROW 0x2c , < arrow pointing left
+ACS_UARROW 0x2d \- \*^ arrow pointing up
+ACS_DARROW 0x2e . v arrow pointing down
+ACS_BLOCK 0x30 0 # solid square block
+ACS_DIAMOND 0x60 \(ga + diamond
+ACS_CKBOARD 0x61 a : checker board (stipple)
+ACS_DEGREE 0x66 f \e degree symbol
+ACS_PLMINUS 0x67 g # plus/minus
+ACS_BOARD 0x68 h # board of squares
+ACS_LANTERN 0x69 i # lantern symbol
+ACS_LRCORNER 0x6a j + lower right corner
+ACS_URCORNER 0x6b k + upper right corner
+ACS_ULCORNER 0x6c l + upper left corner
+ACS_LLCORNER 0x6d m + lower left corner
+ACS_PLUS 0x6e n + large plus or crossover
+ACS_S1 0x6f o \*~ scan line 1
+ACS_S3 0x70 p \- scan line 3
+ACS_HLINE 0x71 q \- horizontal line
+ACS_S7 0x72 r \- scan line 7
+ACS_S9 0x73 s \&_ scan line 9
+ACS_LTEE 0x74 t + tee pointing right
+ACS_RTEE 0x75 u + tee pointing left
+ACS_BTEE 0x76 v + tee pointing up
+ACS_TTEE 0x77 w + tee pointing down
+ACS_VLINE 0x78 x | vertical line
+ACS_LEQUAL 0x79 y < less-than-or-equal-to
+ACS_GEQUAL 0x7a z > greater-than-or-equal-to
+ACS_PI 0x7b { * greek pi
+ACS_NEQUAL 0x7c | ! not-equal
+ACS_STERLING 0x7d } f UK pound sign
+ACS_BULLET 0x7e \*~ o bullet
.TE
.PP
A few notes apply to the table itself:
as the corresponding graphic.
Then read off the VT100/your terminal
character pairs right to left in sequence; these become the ACSC string.
-.SS Color Handling
+.SS "Color Handling"
The curses library functions \fBinit_pair\fP and \fBinit_color\fP
manipulate the \fIcolor pairs\fP and \fIcolor values\fP discussed in this
section
(where \fIN\fP is usually 8),
and can set
character-cell foreground and background characters independently, mixing them
-into \fIN\fP\ *\ \fIN\fP color-pairs.
+into \fIN\fP\ *\ \fIN\fP color pairs.
.bP
On HP-like terminals, the user must set each color
pair up separately (foreground and background are not independently settable).
-Up to \fIM\fP color-pairs may be set up from 2*\fIM\fP different colors.
+Up to \fIM\fP color pairs may be set up from 2*\fIM\fP different colors.
ANSI-compatible terminals are Tektronix-like.
.PP
Some basic color capabilities are independent of the color method.
The numeric
capabilities \fBcolors\fP and \fBpairs\fP specify the maximum numbers of colors
-and color-pairs that can be displayed simultaneously.
+and color pairs that can be displayed simultaneously.
The \fBop\fP (original
pair) string resets foreground and background colors to their default values
for the terminal.
-The \fBoc\fP string resets all colors or color-pairs to
+The \fBoc\fP string resets all colors or color pairs to
their default values for the terminal.
Some terminals (including many PC
terminal emulators) erase screen areas with the current background color rather
-than the power-up default background; these should have the boolean capability
+than the power-up default background; these should have the Boolean capability
\fBbce\fP.
.PP
While the curses library works with \fIcolor pairs\fP
single numeric argument each.
Argument values 0-7 of \fBsetaf\fP/\fBsetab\fP are portably defined as
follows (the middle column is the symbolic #define available in the header for
-the \fBcurses\fP or \fBncurses\fP libraries).
+the \fBcurses\fP or \fI\%ncurses\fP libraries).
The terminal hardware is free to
map these as it likes, but the RGB values indicate normal locations in color
space.
.PP
-.TS H
+.TS
center;
-l c c c
-l l n l.
-\fBColor #define Value RGB\fP
-black \fBCOLOR_BLACK\fP 0 0, 0, 0
-red \fBCOLOR_RED\ \fP 1 max,0,0
-green \fBCOLOR_GREEN\fP 2 0,max,0
-yellow \fBCOLOR_YELLOW\fP 3 max,max,0
-blue \fBCOLOR_BLUE\fP 4 0,0,max
-magenta \fBCOLOR_MAGENTA\fP 5 max,0,max
-cyan \fBCOLOR_CYAN\fP 6 0,max,max
-white \fBCOLOR_WHITE\fP 7 max,max,max
+cb cb cb cb s s
+l lb c l1 l1 l .
+Color #define Value RGB
+_
+black COLOR_BLACK 0 0, 0, 0
+red COLOR_RED 1 max, 0, 0
+green COLOR_GREEN 2 0, max, 0
+yellow COLOR_YELLOW 3 max, max, 0
+blue COLOR_BLUE 4 0, 0, max
+magenta COLOR_MAGENTA 5 max, 0, max
+cyan COLOR_CYAN 6 0, max, max
+white COLOR_WHITE 7 max, max, max
.TE
+.br
+.if t .ne 6v
.PP
The argument values of \fBsetf\fP/\fBsetb\fP historically correspond to
a different mapping, i.e.,
-.TS H
+.PP
+.TS
center;
-l c c c
-l l n l.
-\fBColor #define Value RGB\fP
-black \fBCOLOR_BLACK\fP 0 0, 0, 0
-blue \fBCOLOR_BLUE\fP 1 0,0,max
-green \fBCOLOR_GREEN\fP 2 0,max,0
-cyan \fBCOLOR_CYAN\fP 3 0,max,max
-red \fBCOLOR_RED\ \fP 4 max,0,0
-magenta \fBCOLOR_MAGENTA\fP 5 max,0,max
-yellow \fBCOLOR_YELLOW\fP 6 max,max,0
-white \fBCOLOR_WHITE\fP 7 max,max,max
+cb cb cb cb s s
+l lb c l1 l1 l .
+Color #define Value RGB
+_
+black COLOR_BLACK 0 0, 0, 0
+blue COLOR_BLUE 1 0, 0, max
+green COLOR_GREEN 2 0, max, 0
+cyan COLOR_CYAN 3 0, max, max
+red COLOR_RED 4 max, 0, 0
+magenta COLOR_MAGENTA 5 max, 0, max
+yellow COLOR_YELLOW 6 max, max, 0
+white COLOR_WHITE 7 max, max, max
.TE
.PP
It is important to not confuse the two sets of color capabilities;
otherwise red/blue will be interchanged on the display.
.PP
-On an HP-like terminal, use \fBscp\fP with a color-pair number parameter to set
+On an HP-like terminal, use \fBscp\fP with a color pair number parameter to set
which color pair is current.
.PP
Some terminals allow the \fIcolor values\fP to be modified:
describe the color.
These three parameters default to being interpreted as RGB
(Red, Green, Blue) values.
-If the boolean capability \fBhls\fP is present,
+If the Boolean capability \fBhls\fP is present,
they are instead as HLS (Hue, Lightness, Saturation) indices.
The ranges are
terminal-dependent.
.bP
On an HP-like terminal, \fBinitp\fP may give a capability for changing a
-color-pair value.
-It will take seven parameters; a color-pair number (0 to
+color pair value.
+It will take seven parameters; a color pair number (0 to
\fBmax_pairs\fP \- 1), and two triples describing first background and then
foreground colors.
These parameters must be (Red, Green, Blue) or
On some color terminals, colors collide with highlights.
You can register
these collisions with the \fBncv\fP capability.
-This is a bit-mask of
+This is a bit mask of
attributes not to be used when colors are enabled.
The correspondence with the
attributes understood by \fBcurses\fP is as follows:
.PP
.TS
center;
-l l l l
-lw20 lw2 lw10 lw10.
-\fBAttribute Bit Decimal Set by\fP
+cb cb cb cb
+lb n n lb.
+Attribute Bit Decimal Set by
+_
A_STANDOUT 0 1 sgr
A_UNDERLINE 1 2 sgr
A_REVERSE 2 4 sgr
-A_BLINK 3 8 sgr
-A_DIM 4 16 sgr
-A_BOLD 5 32 sgr
-A_INVIS 6 64 sgr
+A_BLINK 3 8 sgr
+A_DIM 4 16 sgr
+A_BOLD 5 32 sgr
+A_INVIS 6 64 sgr
A_PROTECT 7 128 sgr
A_ALTCHARSET 8 256 sgr
A_HORIZONTAL 9 512 sgr1
These should have
an \fBncv\fP capability of 2.
.PP
-SVr4 curses does nothing with \fBncv\fP, ncurses recognizes it and optimizes
+SVr4 curses does nothing with \fBncv\fP,
+\fI\%ncurses\fP recognizes it and optimizes
the output in favor of colors.
.SS Miscellaneous
If the terminal requires other than a null (zero) character as a pad, then this
can be given as pad.
Only the first character of the pad string is used.
If the terminal does not have a pad character, specify npc.
-Note that ncurses implements the termcap-compatible \fBPC\fP variable;
+Note that \fI\%ncurses\fP implements the termcap-compatible \fBPC\fP
+variable;
though the application may set this value to something other than
-a null, ncurses will test \fBnpc\fP first and use napms if the terminal
+a null,
+\fI\%ncurses\fP will test \fBnpc\fP first and use napms if the terminal
has no pad character.
.PP
If the terminal can move up or down half a line,
.BR rep .
The first parameter is the character to be repeated and the second
is the number of times to repeat it.
-Thus, tparm(repeat_char, \(aqx\(aq, 10) is the same as \*(``xxxxxxxxxx\*(''.
+Thus, tparm(repeat_char, \*'x\*', 10) is the same as \*(``xxxxxxxxxx\*(''.
.PP
If the terminal has a settable command character,
such as the \s-1TEKTRONIX\s+1 4025,
This character is given in the
.B cmdch
capability to identify it.
-The following convention is supported on some UNIX systems:
+The following convention is supported on some Unix systems:
The environment is to be searched for a
.B CC
variable, and if found, all
indicates that the number of lines is not fixed,
but that there is still more memory than fits on the screen.
.PP
-If the terminal is one of those supported by the \s-1UNIX\s+1 virtual
+If the terminal is one of those supported by the Unix virtual
terminal protocol, the terminal number can be given as
.BR vt .
.PP
is transparently passed to the printer while an
.B mc5p
is in effect.
-.SS Glitches and Braindamage
+.SS "Glitches and Brain Damage"
Hazeltine terminals,
-which do not allow \*(``~\*('' characters to be displayed should
+which do not allow \*(``\*~\*('' characters to be displayed should
indicate \fBhz\fP.
.PP
Terminals which ignore a line-feed immediately after an \fBam\fP wrap,
the cursor on top of a \*(``magic cookie\*('',
that to erase standout mode it is instead necessary to use
delete and insert line.
-The ncurses implementation ignores this glitch.
+The \fI\%ncurses\fP implementation ignores this glitch.
.PP
The Beehive Superbee, which is unable to correctly transmit the escape
or control/C characters, has
.PP
Other specific terminal problems may be corrected by adding more
capabilities of the form \fBx\fIx\fR.
-.SS Pitfalls of Long Entries
+.SS "Pitfalls of Long Entries"
Long terminfo entries are unlikely to be a problem; to date, no entry has even
approached terminfo's 4096-byte string-table maximum.
Unfortunately, the termcap
here but will return incorrect data for the terminal.
.PP
The \*(``after tc expansion\*('' length will have a similar effect to the
-above, but only for people who actually set TERM to that terminal
+above, but only for people who actually set \fITERM\fP to that terminal
type, since \fBtgetent\fP only does \*(``tc\*('' expansion once it is found the
terminal type it was looking for, not while searching.
.PP
dump, warnings, or incorrect operation.
If it is too long even before
\*(``tc\*('' expansion, it will have this effect even for users of some other
-terminal types and users whose TERM variable does not have a termcap
+terminal types and users whose \fITERM\fP variable does not have a termcap
entry.
.PP
-When in \-C (translate to termcap) mode, the \fBncurses\fP implementation of
+When in \-C (translate to termcap) mode,
+the \fI\%ncurses\fP implementation of
\fB@TIC@\fP(1M) issues warning messages when the pre-tc length of a termcap
translation is too long.
The \-c (check) option also checks resolved (after tc
expansion) lengths.
-.SS Binary Compatibility
-It is not wise to count on portability of binary terminfo entries between
-commercial UNIX versions.
-The problem is that there are at least two versions
-of terminfo (under HP\-UX and AIX) which diverged from System V terminfo after
-SVr1, and have added extension capabilities to the string table that (in the
-binary format) collide with System V and XSI Curses extensions.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database directory
.SH EXTENSIONS
Searching for terminal descriptions in
-\fB$HOME/.terminfo\fP and TERMINFO_DIRS
+\fI$HOME/.terminfo\fP and \fI\%TERMINFO_DIRS\fP
is not supported by older implementations.
.PP
Some SVr4 \fBcurses\fP implementations, and all previous to SVr4, do not
SVr4/XPG4 do not specify whether \fBmsgr\fP licenses movement while in
an alternate-character-set mode (such modes may, among other things, map
CR and NL to characters that do not trigger local motions).
-The \fBncurses\fP implementation ignores \fBmsgr\fP in \fBALTCHARSET\fP
-mode.
+The \fI\%ncurses\fP implementation ignores \fBmsgr\fP in
+\fBALTCHARSET\fP mode.
This raises the possibility that an XPG4
implementation making the opposite interpretation may need terminfo
-entries made for \fBncurses\fP to have \fBmsgr\fP turned off.
+entries made for \fI\%ncurses\fP to have \fBmsgr\fP turned off.
.PP
-The \fBncurses\fP library handles insert-character and insert-character modes
-in a slightly non-standard way to get better update efficiency.
+The \fI\%ncurses\fP library handles insert-character and
+insert-character modes in a slightly non-standard way to get better
+update efficiency.
See
the \fBInsert/Delete Character\fP subsection above.
.PP
The parameter substitutions for \fBset_clock\fP and \fBdisplay_clock\fP are
-not documented in SVr4 or the XSI Curses standard.
+not documented in SVr4 or X/Open Curses.
They are deduced from the
documentation for the AT&T 505 terminal.
.PP
Be careful assigning the \fBkmous\fP capability.
-The \fBncurses\fP library wants to interpret it as \fBKEY_MOUSE\fP,
+The \fI\%ncurses\fP library wants to interpret it as \fBKEY_MOUSE\fP,
for use by terminals and emulators like xterm
that can return mouse-tracking information in the keyboard-input stream.
.PP
If italics should work with colors,
then the \fBncv\fP value must be specified, even if it is zero.
.PP
-Different commercial ports of terminfo and curses support different subsets of
-the XSI Curses standard and (in some cases) different extension sets.
-Here
-is a summary, accurate as of October 1995:
-.bP
-\fBSVR4, Solaris, ncurses\fP \-\-
-These support all SVr4 capabilities.
-.bP
-\fBSGI\fP \-\-
-Supports the SVr4 set, adds one undocumented extended string
-capability (\fBset_pglen\fP).
-.bP
-\fBSVr1, Ultrix\fP \-\-
-These support a restricted subset of terminfo capabilities.
-The booleans end with \fBxon_xoff\fP;
-the numerics with \fBwidth_status_line\fP;
-and the strings with \fBprtr_non\fP.
+Different commercial ports of \fI\%terminfo\fP and \fIcurses\fP support
+different subsets of X/Open Curses and
+(in some cases)
+different extensions.
+Here is a summary,
+accurate as of October 1995,
+after which the commercial Unix market contracted and lost diversity.
.bP
-\fBHP/UX\fP \-\-
-Supports the SVr1 subset, plus the SVr[234] numerics \fBnum_labels\fP,
-\fBlabel_height\fP, \fBlabel_width\fP, plus function keys 11 through 63, plus
-\fBplab_norm\fP, \fBlabel_on\fP, and \fBlabel_off\fP, plus some incompatible
-extensions in the string table.
+SVr4,
+Solaris,
+and \fI\%ncurses\fP support all SVr4 capabilities.
.bP
-\fBAIX\fP \-\-
-Supports the SVr1 subset, plus function keys 11 through 63, plus a number
-of incompatible string table extensions.
+IRIX supports the SVr4 set and adds one undocumented extended string
+capability (\fB\%set_pglen\fP).
.bP
-\fBOSF\fP \-\-
-Supports both the SVr4 set and the AIX extensions.
-.SH FILES
-.TP 25
-\*d/?/*
-files containing terminal descriptions
-.SH SEE ALSO
-.na
-.hy 0
-\fB@INFOCMP@\fP(1M),
-\fB@TABS@\fP(1),
-\fB@TIC@\fP(1M),
-\fBcurses\fP(3X),
-\fBcurs_color\fP(3X),
-\fBcurs_variables\fP(3X),
-\fBprintf\fP(3),
-\fBterm_variables\fP(3X).
-\fBterm\fP(\*n).
-\fBuser_caps\fP(5).
+SVr1 and Ultrix support a restricted subset of \fI\%terminfo\fP
+capabilities.
+The Booleans end with \fB\%xon_xoff\fP;
+the numerics with \fB\%width_status_line\fP;
+and the strings with \fB\%prtr_non\fP.
+.bP
+HP/UX supports the SVr1 subset,
+plus the SVr[234] numerics
+\fB\%num_labels\fP,
+\fB\%label_height\fP,
+\fB\%label_width\fP,
+plus function keys 11 through 63,
+plus
+\fB\%plab_norm\fP,
+\fB\%label_on\fP,
+and
+\fB\%label_off\fP,
+plus a number of incompatible string table extensions.
+.bP
+AIX supports the SVr1 subset,
+plus function keys 11 through 63,
+plus a number of incompatible string table extensions.
+.bP
+OSF/1 supports both the SVr4 set and the AIX extensions.
+.SH PORTABILITY
+Do not count on compiled (binary) \fI\%terminfo\fP entries being
+portable between commercial Unix systems.
+At least two implementations of \fI\%terminfo\fP
+(those of HP-UX and AIX)
+diverged from those of other System V Unices after SVr1,
+adding extension capabilities to the string table that
+(in the binary format)
+collide with subsequent System V and X/Open Curses extensions.
.SH AUTHORS
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
Based on \fIpcurses\fP by Pavel Curtis.
+.SH SEE ALSO
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TABS@\fP(1),
+\fB\%@TIC@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%curs_color\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%printf\fP(3),
+\fB\%term_variables\fP(3X),
+\fB\%term\fP(5),
+\fB\%user_caps\fP(5)
projects / ncurses.git / blobdiff