« back to all changes in this revision
Viewing changes to doc/html/man/terminfo.5.html
- browse files at revision 11
- compare with another revision
- download diff
- download tarball
- view history from revision 11
- Committer: Bazaar Package Importer
- Author(s): Matthias Klose
- Date: 2007-05-17 09:00:42 UTC
- mfrom: (1.1.3 upstream)
- Revision ID: james.westby@ubuntu.com-20070517090042-86fgxrr6j5jzagot
Tags: 5.6-0ubuntu1
* New upstream version.
- Remove patches applied upstream: ncurses.upstream, signed-chars.
- Update patches: debian-backspace.
* Build-depend on g++-multilib instead of lib{32,64}c*-dev-*.
- Remove patches applied upstream: ncurses.upstream, signed-chars.
- Update patches: debian-backspace.
* Build-depend on g++-multilib instead of lib{32,64}c*-dev-*.
- files added:
- AUTHORS
- files removed:
- debian/patches/ncurses-upstream.patch
- files modified:
- ANNOUNCE
added
removed
doc/html/man/terminfo.5.html
6
6
* Note: this must be run through tbl before nroff.
7
7
* The magic cookie on the first line triggers this under some man programs.
8
8
****************************************************************************
9
* Copyright (c) 1998-2002,2004 Free Software Foundation, Inc. *
9
* Copyright (c) 1998-2004,2006 Free Software Foundation, Inc. *
10
10
* *
11
11
* Permission is hereby granted, free of charge, to any person obtaining a *
12
12
* copy of this software and associated documentation files (the *
32
32
* sale, use or other dealings in this Software without prior written *
33
33
* authorization. *
34
34
****************************************************************************
35
* @Id: terminfo.head,v 1.12 2004/09/25 19:07:11 tom Exp @
35
* @Id: terminfo.head,v 1.13 2006/05/13 15:35:45 tom Exp @
36
36
* Head of terminfo man page ends here
37
* @Id: terminfo.tail,v 1.42 2005/06/25 22:46:03 tom Exp @
37
* @Id: terminfo.tail,v 1.44 2006/04/01 22:47:01 tom Exp @
38
38
* Beginning of terminfo.tail file
39
* This file is part of ncurses.
39
40
* See "terminfo.head" for copyright.
40
41
*.in -2
41
42
*.in +2
76
77
libraries such as <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. <EM>Terminfo</EM> describes termi-
77
78
nals by giving a set of capabilities which they have, by
78
79
specifying how to perform screen operations, and by speci-
79
fying padding requirements and initialization sequences.
80
fying padding requirements and initialization sequences.
81
This describes <STRONG>ncurses</STRONG> version 5.5 (patch 20061209).
80
82
81
83
Entries in <EM>terminfo</EM> consist of a sequence of `,' separated
82
84
fields (embedded commas may be escaped with a backslash or
83
notated as \054). White space after the `,' separator is
84
ignored. The first entry for each terminal gives the
85
names which are known for the terminal, separated by `|'
86
characters. The first name given is the most common
87
abbreviation for the terminal, the last name given should
88
be a long name fully identifying the terminal, and all
89
others are understood as synonyms for the terminal name.
85
notated as \054). White space after the `,' separator is
86
ignored. The first entry for each terminal gives the
87
names which are known for the terminal, separated by `|'
88
characters. The first name given is the most common
89
abbreviation for the terminal, the last name given should
90
be a long name fully identifying the terminal, and all
91
others are understood as synonyms for the terminal name.
90
92
All names but the last should be in lower case and contain
91
no blanks; the last name may well contain upper case and
93
no blanks; the last name may well contain upper case and
92
94
blanks for readability.
93
95
94
96
Lines beginning with a `#' in the first column are treated
95
as comments. While comment lines are legal at any point,
96
the output of <EM>captoinfo</EM> and <EM>infotocap</EM> (aliases for <EM>tic</EM>)
97
as comments. While comment lines are legal at any point,
98
the output of <EM>captoinfo</EM> and <EM>infotocap</EM> (aliases for <EM>tic</EM>)
97
99
will move comments so they occur only between entries.
98
100
99
Newlines and leading tabs may be used for formatting
100
entries for readability. These are removed from parsed
101
entries. The <EM>infocmp</EM> <EM>-f</EM> option relies on this to format
101
Newlines and leading tabs may be used for formatting
102
entries for readability. These are removed from parsed
103
entries. The <EM>infocmp</EM> <EM>-f</EM> option relies on this to format
102
104
if-then-else expressions: the result can be read by <EM>tic</EM>.
103
105
104
106
Terminal names (except for the last, verbose entry) should
105
107
be chosen using the following conventions. The particular
106
piece of hardware making up the terminal should have a
107
root name, thus ``hp2621''. This name should not contain
108
piece of hardware making up the terminal should have a
109
root name, thus ``hp2621''. This name should not contain
108
110
hyphens. Modes that the hardware can be in, or user pref-
109
erences, should be indicated by appending a hyphen and a
110
mode suffix. Thus, a vt100 in 132 column mode would be
111
erences, should be indicated by appending a hyphen and a
112
mode suffix. Thus, a vt100 in 132 column mode would be
111
113
vt100-w. The following suffixes should be used where pos-
112
114
sible:
113
115
124
126
-ns No status line hp2626-ns
125
127
-rv Reverse video c100-rv
126
128
-s Enable status line vt100-s
129
127
130
-vb Use visible bell instead of beep wy370-vb
128
129
131
-w Wide mode (> 80 columns, usually 132) vt100-w
130
132
131
For more on terminal naming conventions, see the <STRONG>term(7)</STRONG>
133
For more on terminal naming conventions, see the <STRONG>term(7)</STRONG>
132
134
manual page.
133
135
134
136
<STRONG>Capabilities</STRONG>
135
The following is a complete table of the capabilities
136
included in a terminfo description block and available to
137
The following is a complete table of the capabilities
138
included in a terminfo description block and available to
137
139
terminfo-using code. In each line of the table,
138
140
139
The <STRONG>variable</STRONG> is the name by which the programmer (at the
141
The <STRONG>variable</STRONG> is the name by which the programmer (at the
140
142
terminfo level) accesses the capability.
141
143
142
The <STRONG>capname</STRONG> is the short name used in the text of the
143
database, and is used by a person updating the database.
144
Whenever possible, capnames are chosen to be the same as
144
The <STRONG>capname</STRONG> is the short name used in the text of the
145
database, and is used by a person updating the database.
146
Whenever possible, capnames are chosen to be the same as
145
147
or similar to the ANSI X3.64-1979 standard (now superseded
146
by ECMA-48, which uses identical or very similar names).
148
by ECMA-48, which uses identical or very similar names).
147
149
Semantics are also intended to match those of the specifi-
148
150
cation.
149
151
150
The termcap code is the old <STRONG>termcap</STRONG> capability name (some
152
The termcap code is the old <STRONG>termcap</STRONG> capability name (some
151
153
capabilities are new, and have names which termcap did not
152
154
originate).
153
155
154
Capability names have no hard length limit, but an infor-
155
mal limit of 5 characters has been adopted to keep them
156
short and to allow the tabs in the source file <STRONG>Caps</STRONG> to
156
Capability names have no hard length limit, but an infor-
157
mal limit of 5 characters has been adopted to keep them
158
short and to allow the tabs in the source file <STRONG>Caps</STRONG> to
157
159
line up nicely.
158
160
159
Finally, the description field attempts to convey the
160
semantics of the capability. You may find some codes in
161
Finally, the description field attempts to convey the
162
semantics of the capability. You may find some codes in
161
163
the description field:
162
164
163
165
(P) indicates that padding may be specified
164
166
165
#[1-9] in the description field indicates that the string
167
#[1-9] in the description field indicates that the string
166
168
is passed through tparm with parms as given (#<EM>i</EM>).
167
169
168
(P*) indicates that padding may vary in proportion to
170
(P*) indicates that padding may vary in proportion to
169
171
the number of lines affected
170
172
171
173
(#<EM>i</EM>) indicates the <EM>i</EM>th parameter.
191
193
for hpa/mhpa caps
192
194
193
195
194
195
196
cpi_changes_res cpix YF changing character
196
197
pitch changes reso-
197
198
lution
304
305
width_status_line wsl ws number of columns in
305
306
status line
306
307
307
The following numeric capabilities are present in the
308
SVr4.0 term structure, but are not yet documented in the
308
The following numeric capabilities are present in the
309
SVr4.0 term structure, but are not yet documented in the
309
310
man page. They came in with SVr4's printer support.
310
311
311
312
903
904
zero_motion zerom Zx No motion for subse-
904
905
quent character
905
906
906
The following string capabilities are present in the
907
SVr4.0 term structure, but were originally not documented
907
The following string capabilities are present in the
908
SVr4.0 term structure, but were originally not documented
908
909
in the man page.
909
910
910
911
988
989
bottom margins to
989
990
#1, #2
990
991
991
The XSI Curses standard added these. They are some
992
post-4.1 versions of System V curses, e.g., Solaris 2.5
993
and IRIX 6.x. The <STRONG>ncurses</STRONG> termcap names for them are
992
The XSI Curses standard added these. They are some
993
post-4.1 versions of System V curses, e.g., Solaris 2.5
994
and IRIX 6.x. The <STRONG>ncurses</STRONG> termcap names for them are
994
995
invented; according to the XSI Curses standard, they have
995
no termcap names. If your compiled terminfo entries use
996
these, they may not be binary-compatible with System V
996
no termcap names. If your compiled terminfo entries use
997
these, they may not be binary-compatible with System V
997
998
terminfo entries after SVr4.1; beware!
998
999
999
1000
1018
1019
to #1 hundredth of
1019
1020
an inch
1020
1021
1021
1022
1022
<STRONG>A</STRONG> <STRONG>Sample</STRONG> <STRONG>Entry</STRONG>
1023
1023
The following entry, describing an ANSI-standard terminal,
1024
is representative of what a <STRONG>terminfo</STRONG> entry for a modern
1024
is representative of what a <STRONG>terminfo</STRONG> entry for a modern
1025
1025
terminal typically looks like.
1026
1026
1027
1027
ansi|ansi/pc-term compatible with color,
1045
1045
sgr0=\E[0;10m, tbc=\E[2g, u6=\E[%d;%dR, u7=\E[6n,
1046
1046
u8=\E[?%[;0123456789]c, u9=\E[c, vpa=\E[%p1%dd,
1047
1047
1048
Entries may continue onto multiple lines by placing white
1049
space at the beginning of each line except the first.
1050
Comments may be included on lines beginning with ``#''.
1048
Entries may continue onto multiple lines by placing white
1049
space at the beginning of each line except the first.
1050
Comments may be included on lines beginning with ``#''.
1051
1051
Capabilities in <EM>terminfo</EM> are of three types: Boolean capa-
1052
bilities which indicate that the terminal has some
1053
particular feature, numeric capabilities giving the size
1054
of the terminal or the size of particular delays, and
1055
string capabilities, which give a sequence which can be
1056
used to perform particular terminal operations.
1052
bilities which indicate that the terminal has some partic-
1053
ular feature, numeric capabilities giving the size of the
1054
terminal or the size of particular delays, and string
1055
capabilities, which give a sequence which can be used to
1056
perform particular terminal operations.
1057
1057
1058
1058
1059
1059
<STRONG>Types</STRONG> <STRONG>of</STRONG> <STRONG>Capabilities</STRONG>
1060
All capabilities have names. For instance, the fact that
1061
ANSI-standard terminals have <EM>automatic</EM> <EM>margins</EM> (i.e., an
1062
automatic return and line-feed when the end of a line is
1063
reached) is indicated by the capability <STRONG>am</STRONG>. Hence the
1060
All capabilities have names. For instance, the fact that
1061
ANSI-standard terminals have <EM>automatic</EM> <EM>margins</EM> (i.e., an
1062
automatic return and line-feed when the end of a line is
1063
reached) is indicated by the capability <STRONG>am</STRONG>. Hence the
1064
1064
description of ansi includes <STRONG>am</STRONG>. Numeric capabilities are
1065
followed by the character `#' and then a positive value.
1066
Thus <STRONG>cols</STRONG>, which indicates the number of columns the ter-
1067
minal has, gives the value `80' for ansi. Values for
1065
followed by the character `#' and then a positive value.
1066
Thus <STRONG>cols</STRONG>, which indicates the number of columns the ter-
1067
minal has, gives the value `80' for ansi. Values for
1068
1068
numeric capabilities may be specified in decimal, octal or
1069
hexadecimal, using the C programming language conventions
1069
hexadecimal, using the C programming language conventions
1070
1070
(e.g., 255, 0377 and 0xff or 0xFF).
1071
1071
1072
Finally, string valued capabilities, such as <STRONG>el</STRONG> (clear to
1072
Finally, string valued capabilities, such as <STRONG>el</STRONG> (clear to
1073
1073
end of line sequence) are given by the two-character code,
1074
an `=', and then a string ending at the next following
1074
an `=', and then a string ending at the next following
1075
1075
`,'.
1076
1076
1077
A number of escape sequences are provided in the string
1077
A number of escape sequences are provided in the string
1078
1078
valued capabilities for easy encoding of characters there.
1079
Both <STRONG>\E</STRONG> and <STRONG>\e</STRONG> map to an ESCAPE character, <STRONG>^x</STRONG> maps to a
1080
control-x for any appropriate x, and the sequences <STRONG>\n</STRONG> <STRONG>\l</STRONG>
1081
<STRONG>\r</STRONG> <STRONG>\t</STRONG> <STRONG>\b</STRONG> <STRONG>\f</STRONG> <STRONG>\s</STRONG> give a newline, line-feed, return, tab,
1079
Both <STRONG>\E</STRONG> and <STRONG>\e</STRONG> map to an ESCAPE character, <STRONG>^x</STRONG> maps to a
1080
control-x for any appropriate x, and the sequences <STRONG>\n</STRONG> <STRONG>\l</STRONG>
1081
<STRONG>\r</STRONG> <STRONG>\t</STRONG> <STRONG>\b</STRONG> <STRONG>\f</STRONG> <STRONG>\s</STRONG> give a newline, line-feed, return, tab,
1082
1082
backspace, form-feed, and space. Other escapes include <STRONG>\^</STRONG>
1083
for <STRONG>^</STRONG>, <STRONG>\\</STRONG> for <STRONG>\</STRONG>, <STRONG>\</STRONG>, for comma, <STRONG>\:</STRONG> for <STRONG>:</STRONG>, and <STRONG>\0</STRONG> for null.
1084
(<STRONG>\0</STRONG> will produce \200, which does not terminate a string
1083
for <STRONG>^</STRONG>, <STRONG>\\</STRONG> for <STRONG>\</STRONG>, <STRONG>\</STRONG>, for comma, <STRONG>\:</STRONG> for <STRONG>:</STRONG>, and <STRONG>\0</STRONG> for null.
1084
(<STRONG>\0</STRONG> will produce \200, which does not terminate a string
1085
1085
but behaves as a null character on most terminals, provid-
1086
ing CS7 is specified. See <STRONG><A HREF="stty.1.html">stty(1)</A></STRONG>.) Finally, characters
1086
ing CS7 is specified. See <STRONG><A HREF="stty.1.html">stty(1)</A></STRONG>.) Finally, characters
1087
1087
may be given as three octal digits after a <STRONG>\</STRONG>.
1088
1088
1089
A delay in milliseconds may appear anywhere in a string
1090
capability, enclosed in $<..> brackets, as in <STRONG>el</STRONG>=\EK$<5>,
1091
and padding characters are supplied by <EM>tputs</EM> to provide
1092
this delay. The delay must be a number with at most one
1089
A delay in milliseconds may appear anywhere in a string
1090
capability, enclosed in $<..> brackets, as in <STRONG>el</STRONG>=\EK$<5>,
1091
and padding characters are supplied by <EM>tputs</EM> to provide
1092
this delay. The delay must be a number with at most one
1093
1093
decimal place of precision; it may be followed by suffixes
1094
`*' or '/' or both. A `*' indicates that the padding
1095
required is proportional to the number of lines affected
1096
by the operation, and the amount given is the per-
1097
affected-unit padding required. (In the case of insert
1094
`*' or '/' or both. A `*' indicates that the padding
1095
required is proportional to the number of lines affected
1096
by the operation, and the amount given is the per-
1097
affected-unit padding required. (In the case of insert
1098
1098
character, the factor is still the number of <EM>lines</EM>
1099
affected.) Normally, padding is advisory if the device
1100
has the <STRONG>xon</STRONG> capability; it is used for cost computation
1101
but does not trigger delays. A `/' suffix indicates that
1102
the padding is mandatory and forces a delay of the given
1103
number of milliseconds even on devices for which <STRONG>xon</STRONG> is
1099
affected.) Normally, padding is advisory if the device
1100
has the <STRONG>xon</STRONG> capability; it is used for cost computation
1101
but does not trigger delays. A `/' suffix indicates that
1102
the padding is mandatory and forces a delay of the given
1103
number of milliseconds even on devices for which <STRONG>xon</STRONG> is
1104
1104
present to indicate flow control.
1105
1105
1106
Sometimes individual capabilities must be commented out.
1107
To do this, put a period before the capability name. For
1106
Sometimes individual capabilities must be commented out.
1107
To do this, put a period before the capability name. For
1108
1108
example, see the second <STRONG>ind</STRONG> in the example above.
1109
1109
1110
1110
1111
1111
<STRONG>Fetching</STRONG> <STRONG>Compiled</STRONG> <STRONG>Descriptions</STRONG>
1112
If the environment variable TERMINFO is set, it is inter-
1113
preted as the pathname of a directory containing the com-
1112
If the environment variable TERMINFO is set, it is inter-
1113
preted as the pathname of a directory containing the com-
1114
1114
piled description you are working on. Only that directory
1115
1115
is searched.
1116
1116
1117
If TERMINFO is not set, the <STRONG>ncurses</STRONG> version of the ter-
1118
minfo reader code will instead look in the directory
1119
<STRONG>$HOME/.terminfo</STRONG> for a compiled description. If it fails
1120
to find one there, and the environment variable TER-
1121
MINFO_DIRS is set, it will interpret the contents of that
1122
variable as a list of colon- separated directories to be
1123
searched (an empty entry is interpreted as a command to
1124
search <EM>/usr/share/terminfo</EM>). If no description is found
1125
in any of the TERMINFO_DIRS directories, the fetch fails.
1117
If TERMINFO is not set, the <STRONG>ncurses</STRONG> version of the ter-
1118
minfo reader code will instead look in the directory
1119
<STRONG>$HOME/.terminfo</STRONG> for a compiled description. If it fails
1120
to find one there, and the environment variable TER-
1121
MINFO_DIRS is set, it will interpret the contents of that
1122
variable as a list of colon- separated directories to be
1123
searched (an empty entry is interpreted as a command to
1124
search <EM>/usr/share/terminfo</EM>). If no description is found
1125
in any of the TERMINFO_DIRS directories, the fetch fails.
1126
1126
1127
If neither TERMINFO nor TERMINFO_DIRS is set, the last
1128
place tried will be the system terminfo directory,
1127
If neither TERMINFO nor TERMINFO_DIRS is set, the last
1128
place tried will be the system terminfo directory,
1129
1129
<EM>/usr/share/terminfo</EM>.
1130
1130
1131
(Neither the <STRONG>$HOME/.terminfo</STRONG> lookups nor TERMINFO_DIRS
1132
extensions are supported under stock System V ter-
1131
(Neither the <STRONG>$HOME/.terminfo</STRONG> lookups nor TERMINFO_DIRS
1132
extensions are supported under stock System V ter-
1133
1133
minfo/curses.)
1134
1134
1135
1135
1136
1136
<STRONG>Preparing</STRONG> <STRONG>Descriptions</STRONG>
1137
We now outline how to prepare descriptions of terminals.
1138
The most effective way to prepare a terminal description
1139
is by imitating the description of a similar terminal in
1140
<EM>terminfo</EM> and to build up a description gradually, using
1137
We now outline how to prepare descriptions of terminals.
1138
The most effective way to prepare a terminal description
1139
is by imitating the description of a similar terminal in
1140
<EM>terminfo</EM> and to build up a description gradually, using
1141
1141
partial descriptions with <EM>vi</EM> or some other screen-oriented
1142
program to check that they are correct. Be aware that a
1142
program to check that they are correct. Be aware that a
1143
1143
very unusual terminal may expose deficiencies in the abil-
1144
ity of the <EM>terminfo</EM> file to describe it or bugs in the
1144
ity of the <EM>terminfo</EM> file to describe it or bugs in the
1145
1145
screen-handling code of the test program.
1146
1146
1147
To get the padding for insert line right (if the terminal
1147
To get the padding for insert line right (if the terminal
1148
1148
manufacturer did not document it) a severe test is to edit
1149
a large file at 9600 baud, delete 16 or so lines from the
1150
middle of the screen, then hit the `u' key several times
1151
quickly. If the terminal messes up, more padding is usu-
1152
ally needed. A similar test can be used for insert char-
1149
a large file at 9600 baud, delete 16 or so lines from the
1150
middle of the screen, then hit the `u' key several times
1151
quickly. If the terminal messes up, more padding is usu-
1152
ally needed. A similar test can be used for insert char-
1153
1153
acter.
1154
1154
1155
1155
1156
1156
<STRONG>Basic</STRONG> <STRONG>Capabilities</STRONG>
1157
The number of columns on each line for the terminal is
1158
given by the <STRONG>cols</STRONG> numeric capability. If the terminal is
1159
a CRT, then the number of lines on the screen is given by
1157
The number of columns on each line for the terminal is
1158
given by the <STRONG>cols</STRONG> numeric capability. If the terminal is
1159
a CRT, then the number of lines on the screen is given by
1160
1160
the <STRONG>lines</STRONG> capability. If the terminal wraps around to the
1161
beginning of the next line when it reaches the right mar-
1161
beginning of the next line when it reaches the right mar-
1162
1162
gin, then it should have the <STRONG>am</STRONG> capability. If the termi-
1163
nal can clear its screen, leaving the cursor in the home
1164
position, then this is given by the <STRONG>clear</STRONG> string capabil-
1165
ity. If the terminal overstrikes (rather than clearing a
1166
position when a character is struck over) then it should
1167
have the <STRONG>os</STRONG> capability. If the terminal is a printing
1168
terminal, with no soft copy unit, give it both <STRONG>hc</STRONG> and <STRONG>os</STRONG>.
1169
(<STRONG>os</STRONG> applies to storage scope terminals, such as TEKTRONIX
1170
4010 series, as well as hard copy and APL terminals.) If
1163
nal can clear its screen, leaving the cursor in the home
1164
position, then this is given by the <STRONG>clear</STRONG> string capabil-
1165
ity. If the terminal overstrikes (rather than clearing a
1166
position when a character is struck over) then it should
1167
have the <STRONG>os</STRONG> capability. If the terminal is a printing
1168
terminal, with no soft copy unit, give it both <STRONG>hc</STRONG> and <STRONG>os</STRONG>.
1169
(<STRONG>os</STRONG> applies to storage scope terminals, such as TEKTRONIX
1170
4010 series, as well as hard copy and APL terminals.) If
1171
1171
there is a code to move the cursor to the left edge of the
1172
1172
current row, give this as <STRONG>cr</STRONG>. (Normally this will be car-
1173
riage return, control M.) If there is a code to produce
1173
riage return, control M.) If there is a code to produce
1174
1174
an audible signal (bell, beep, etc) give this as <STRONG>bel</STRONG>.
1175
1175
1176
If there is a code to move the cursor one position to the
1177
left (such as backspace) that capability should be given
1178
as <STRONG>cub1</STRONG>. Similarly, codes to move to the right, up, and
1176
If there is a code to move the cursor one position to the
1177
left (such as backspace) that capability should be given
1178
as <STRONG>cub1</STRONG>. Similarly, codes to move to the right, up, and
1179
1179
down should be given as <STRONG>cuf1</STRONG>, <STRONG>cuu1</STRONG>, and <STRONG>cud1</STRONG>. These local
1180
cursor motions should not alter the text they pass over,
1181
for example, you would not normally use `<STRONG>cuf1</STRONG>= ' because
1180
cursor motions should not alter the text they pass over,
1181
for example, you would not normally use `<STRONG>cuf1</STRONG>= ' because
1182
1182
the space would erase the character moved over.
1183
1183
1184
A very important point here is that the local cursor
1185
motions encoded in <EM>terminfo</EM> are undefined at the left and
1186
top edges of a CRT terminal. Programs should never
1187
attempt to backspace around the left edge, unless <STRONG>bw</STRONG> is
1184
A very important point here is that the local cursor
1185
motions encoded in <EM>terminfo</EM> are undefined at the left and
1186
top edges of a CRT terminal. Programs should never
1187
attempt to backspace around the left edge, unless <STRONG>bw</STRONG> is
1188
1188
given, and never attempt to go up locally off the top. In
1189
order to scroll text up, a program will go to the bottom
1189
order to scroll text up, a program will go to the bottom
1190
1190
left corner of the screen and send the <STRONG>ind</STRONG> (index) string.
1191
1191
1192
1192
To scroll text down, a program goes to the top left corner
1193
of the screen and sends the <STRONG>ri</STRONG> (reverse index) string.
1194
The strings <STRONG>ind</STRONG> and <STRONG>ri</STRONG> are undefined when not on their
1193
of the screen and sends the <STRONG>ri</STRONG> (reverse index) string.
1194
The strings <STRONG>ind</STRONG> and <STRONG>ri</STRONG> are undefined when not on their
1195
1195
respective corners of the screen.
1196
1196
1197
1197
Parameterized versions of the scrolling sequences are <STRONG>indn</STRONG>
1198
1198
and <STRONG>rin</STRONG> which have the same semantics as <STRONG>ind</STRONG> and <STRONG>ri</STRONG> except
1199
that they take one parameter, and scroll that many lines.
1200
They are also undefined except at the appropriate edge of
1199
that they take one parameter, and scroll that many lines.
1200
They are also undefined except at the appropriate edge of
1201
1201
the screen.
1202
1202
1203
The <STRONG>am</STRONG> capability tells whether the cursor sticks at the
1204
right edge of the screen when text is output, but this
1203
The <STRONG>am</STRONG> capability tells whether the cursor sticks at the
1204
right edge of the screen when text is output, but this
1205
1205
does not necessarily apply to a <STRONG>cuf1</STRONG> from the last column.
1206
The only local motion which is defined from the left edge
1207
is if <STRONG>bw</STRONG> is given, then a <STRONG>cub1</STRONG> from the left edge will
1208
move to the right edge of the previous row. If <STRONG>bw</STRONG> is not
1209
given, the effect is undefined. This is useful for draw-
1210
ing a box around the edge of the screen, for example. If
1211
the terminal has switch selectable automatic margins, the
1212
<EM>terminfo</EM> file usually assumes that this is on; i.e., <STRONG>am</STRONG>.
1213
If the terminal has a command which moves to the first
1214
column of the next line, that command can be given as <STRONG>nel</STRONG>
1215
(newline). It does not matter if the command clears the
1216
remainder of the current line, so if the terminal has no
1217
<STRONG>cr</STRONG> and <STRONG>lf</STRONG> it may still be possible to craft a working <STRONG>nel</STRONG>
1206
The only local motion which is defined from the left edge
1207
is if <STRONG>bw</STRONG> is given, then a <STRONG>cub1</STRONG> from the left edge will
1208
move to the right edge of the previous row. If <STRONG>bw</STRONG> is not
1209
given, the effect is undefined. This is useful for draw-
1210
ing a box around the edge of the screen, for example. If
1211
the terminal has switch selectable automatic margins, the
1212
<EM>terminfo</EM> file usually assumes that this is on; i.e., <STRONG>am</STRONG>.
1213
If the terminal has a command which moves to the first
1214
column of the next line, that command can be given as <STRONG>nel</STRONG>
1215
(newline). It does not matter if the command clears the
1216
remainder of the current line, so if the terminal has no
1217
<STRONG>cr</STRONG> and <STRONG>lf</STRONG> it may still be possible to craft a working <STRONG>nel</STRONG>
1218
1218
out of one or both of them.
1219
1219
1220
1220
These capabilities suffice to describe hard-copy and
1221
"glass-tty" terminals. Thus the model 33 teletype is
1221
"glass-tty" terminals. Thus the model 33 teletype is
1222
1222
described as
1223
1223
1224
1224
33|tty33|tty|model 33 teletype,
1232
1232
1233
1233
1234
1234
<STRONG>Parameterized</STRONG> <STRONG>Strings</STRONG>
1235
Cursor addressing and other strings requiring parameters
1236
in the terminal are described by a parameterized string
1237
capability, with <STRONG><A HREF="printf.3S.html">printf(3S)</A></STRONG> like escapes <STRONG>%x</STRONG> in it. For
1238
example, to address the cursor, the <STRONG>cup</STRONG> capability is
1235
Cursor addressing and other strings requiring parameters
1236
in the terminal are described by a parameterized string
1237
capability, with <STRONG><A HREF="printf.3S.html">printf(3S)</A></STRONG> like escapes <STRONG>%x</STRONG> in it. For
1238
example, to address the cursor, the <STRONG>cup</STRONG> capability is
1239
1239
given, using two parameters: the row and column to address
1240
1240
to. (Rows and columns are numbered from zero and refer to
1241
1241
the physical screen visible to the user, not to any unseen
1242
memory.) If the terminal has memory relative cursor
1242
memory.) If the terminal has memory relative cursor
1243
1243
addressing, that can be indicated by <STRONG>mrcup</STRONG>.
1244
1244
1245
The parameter mechanism uses a stack and special <STRONG>%</STRONG> codes
1246
to manipulate it. Typically a sequence will push one of
1247
the parameters onto the stack and then print it in some
1248
format. Print (e.g., "%d") is a special case. Other
1249
operations, including "%t" pop their operand from the
1245
The parameter mechanism uses a stack and special <STRONG>%</STRONG> codes
1246
to manipulate it. Typically a sequence will push one of
1247
the parameters onto the stack and then print it in some
1248
format. Print (e.g., "%d") is a special case. Other
1249
operations, including "%t" pop their operand from the
1250
1250
stack. It is noted that more complex operations are often
1251
1251
necessary, e.g., in the <STRONG>sgr</STRONG> string.
1252
1252
1277
1277
%g[A-Z]
1278
1278
get static variable [a-z] and push it
1279
1279
1280
The terms "static" and "dynamic" are misleading.
1281
Historically, these are simply two different sets of
1282
variables, whose values are not reset between calls
1283
to <STRONG>tparm</STRONG>. However, that fact is not documented in
1284
other implementations. Relying on it will adversely
1280
The terms "static" and "dynamic" are misleading.
1281
Historically, these are simply two different sets of
1282
variables, whose values are not reset between calls
1283
to <STRONG>tparm</STRONG>. However, that fact is not documented in
1284
other implementations. Relying on it will adversely
1285
1285
impact portability to other implementations.
1286
1286
1287
1287
%'<EM>c</EM>' char constant <EM>c</EM>
1305
1305
logical AND and OR operations (for conditionals)
1306
1306
1307
1307
%! %~
1308
unary operations (logical and bit complement):
1308
unary operations (logical and bit complement):
1309
1309
push(op pop())
1310
1310
1311
1311
%i add 1 to first two parameters (for ANSI terminals)
1312
1312
1313
1313
%? <EM>expr</EM> %t <EM>thenpart</EM> %e <EM>elsepart</EM> %;
1314
This forms an if-then-else. The %e <EM>elsepart</EM> is
1315
optional. Usually the %? <EM>expr</EM> part pushes a value
1316
onto the stack, and %t pops it from the stack,
1317
testing if it is nonzero (true). If it is zero
1318
(false), control passes to the %e (else) part.
1314
This forms an if-then-else. The %e <EM>elsepart</EM> is
1315
optional. Usually the %? <EM>expr</EM> part pushes a value
1316
onto the stack, and %t pops it from the stack, test-
1317
ing if it is nonzero (true). If it is zero (false),
1318
control passes to the %e (else) part.
1319
1319
1320
1320
It is possible to form else-if's a la Algol 68:
1321
1321
%? c1 %t b1 %e c2 %t b2 %e c3 %t b3 %e c4 %t b4 %e %;
1323
1323
where ci are conditions, bi are bodies.
1324
1324
1325
1325
Use the <STRONG>-f</STRONG> option of <STRONG>tic</STRONG> or <STRONG>infocmp</STRONG> to see the struc-
1326
ture of if-the-else's. Some strings, e.g., <STRONG>sgr</STRONG> can
1326
ture of if-the-else's. Some strings, e.g., <STRONG>sgr</STRONG> can
1327
1327
be very complicated when written on one line. The <STRONG>-f</STRONG>
1328
option splits the string into lines with the parts
1328
option splits the string into lines with the parts
1329
1329
indented.
1330
1330
1331
1331
Binary operations are in postfix form with the operands in
1332
the usual order. That is, to get x-5 one would use
1333
"%gx%{5}%-". %P and %g variables are persistent across
1332
the usual order. That is, to get x-5 one would use
1333
"%gx%{5}%-". %P and %g variables are persistent across
1334
1334
escape-string evaluations.
1335
1335
1336
1336
Consider the HP2645, which, to get to row 3 and column 12,
1337
needs to be sent \E&a12c03Y padded for 6 milliseconds.
1338
Note that the order of the rows and columns is inverted
1339
here, and that the row and column are printed as two dig-
1337
needs to be sent \E&a12c03Y padded for 6 milliseconds.
1338
Note that the order of the rows and columns is inverted
1339
here, and that the row and column are printed as two dig-
1340
1340
its. Thus its <STRONG>cup</STRONG> capability is "cup=6\E&%p2%2dc%p1%2dY".
1341
1341
1342
1342
The Microterm ACT-IV needs the current row and column sent
1343
preceded by a <STRONG>^T</STRONG>, with the row and column simply encoded
1344
in binary, "cup=^T%p1%c%p2%c". Terminals which use "%c"
1345
need to be able to backspace the cursor (<STRONG>cub1</STRONG>), and to
1343
preceded by a <STRONG>^T</STRONG>, with the row and column simply encoded
1344
in binary, "cup=^T%p1%c%p2%c". Terminals which use "%c"
1345
need to be able to backspace the cursor (<STRONG>cub1</STRONG>), and to
1346
1346
move the cursor up one line on the screen (<STRONG>cuu1</STRONG>). This is
1347
necessary because it is not always safe to transmit <STRONG>\n</STRONG> <STRONG>^D</STRONG>
1348
and <STRONG>\r</STRONG>, as the system may change or discard them. (The
1349
library routines dealing with terminfo set tty modes so
1347
necessary because it is not always safe to transmit <STRONG>\n</STRONG> <STRONG>^D</STRONG>
1348
and <STRONG>\r</STRONG>, as the system may change or discard them. (The
1349
library routines dealing with terminfo set tty modes so
1350
1350
that tabs are never expanded, so \t is safe to send. This
1351
1351
turns out to be essential for the Ann Arbor 4080.)
1352
1352
1353
1353
A final example is the LSI ADM-3a, which uses row and col-
1354
1354
umn offset by a blank character, thus "cup=\E=%p1%'
1355
'%+%c%p2%' '%+%c". After sending `\E=', this pushes the
1356
first parameter, pushes the ASCII value for a space (32),
1357
adds them (pushing the sum on the stack in place of the
1358
two previous values) and outputs that value as a charac-
1359
ter. Then the same is done for the second parameter.
1355
'%+%c%p2%' '%+%c". After sending `\E=', this pushes the
1356
first parameter, pushes the ASCII value for a space (32),
1357
adds them (pushing the sum on the stack in place of the
1358
two previous values) and outputs that value as a charac-
1359
ter. Then the same is done for the second parameter.
1360
1360
More complex arithmetic is possible using the stack.
1361
1361
1362
1362
1363
1363
<STRONG>Cursor</STRONG> <STRONG>Motions</STRONG>
1364
1364
If the terminal has a fast way to home the cursor (to very
1365
upper left corner of screen) then this can be given as
1366
<STRONG>home</STRONG>; similarly a fast way of getting to the lower left-
1367
hand corner can be given as <STRONG>ll</STRONG>; this may involve going up
1368
with <STRONG>cuu1</STRONG> from the home position, but a program should
1369
never do this itself (unless <STRONG>ll</STRONG> does) because it can make
1370
no assumption about the effect of moving up from the home
1371
position. Note that the home position is the same as
1365
upper left corner of screen) then this can be given as
1366
<STRONG>home</STRONG>; similarly a fast way of getting to the lower left-
1367
hand corner can be given as <STRONG>ll</STRONG>; this may involve going up
1368
with <STRONG>cuu1</STRONG> from the home position, but a program should
1369
never do this itself (unless <STRONG>ll</STRONG> does) because it can make
1370
no assumption about the effect of moving up from the home
1371
position. Note that the home position is the same as
1372
1372
addressing to (0,0): to the top left corner of the screen,
1373
not of memory. (Thus, the \EH sequence on HP terminals
1373
not of memory. (Thus, the \EH sequence on HP terminals
1374
1374
cannot be used for <STRONG>home</STRONG>.)
1375
1375
1376
1376
If the terminal has row or column absolute cursor address-
1377
ing, these can be given as single parameter capabilities
1377
ing, these can be given as single parameter capabilities
1378
1378
<STRONG>hpa</STRONG> (horizontal position absolute) and <STRONG>vpa</STRONG> (vertical posi-
1379
1379
tion absolute). Sometimes these are shorter than the more
1380
general two parameter sequence (as with the hp2645) and
1380
general two parameter sequence (as with the hp2645) and
1381
1381
can be used in preference to <STRONG>cup</STRONG>. If there are parameter-
1382
ized local motions (e.g., move <EM>n</EM> spaces to the right)
1382
ized local motions (e.g., move <EM>n</EM> spaces to the right)
1383
1383
these can be given as <STRONG>cud</STRONG>, <STRONG>cub</STRONG>, <STRONG>cuf</STRONG>, and <STRONG>cuu</STRONG> with a single
1384
parameter indicating how many spaces to move. These are
1385
primarily useful if the terminal does not have <STRONG>cup</STRONG>, such
1384
parameter indicating how many spaces to move. These are
1385
primarily useful if the terminal does not have <STRONG>cup</STRONG>, such
1386
1386
as the TEKTRONIX 4025.
1387
1387
1388
1388
If the terminal needs to be in a special mode when running
1389
1389
a program that uses these capabilities, the codes to enter
1390
and exit this mode can be given as <STRONG>smcup</STRONG> and <STRONG>rmcup</STRONG>. This
1391
arises, for example, from terminals like the Concept with
1392
more than one page of memory. If the terminal has only
1393
memory relative cursor addressing and not screen relative
1390
and exit this mode can be given as <STRONG>smcup</STRONG> and <STRONG>rmcup</STRONG>. This
1391
arises, for example, from terminals like the Concept with
1392
more than one page of memory. If the terminal has only
1393
memory relative cursor addressing and not screen relative
1394
1394
cursor addressing, a one screen-sized window must be fixed
1395
into the terminal for cursor addressing to work properly.
1395
into the terminal for cursor addressing to work properly.
1396
1396
This is also used for the TEKTRONIX 4025, where <STRONG>smcup</STRONG> sets
1397
the command character to be the one used by terminfo. If
1398
the <STRONG>smcup</STRONG> sequence will not restore the screen after an
1397
the command character to be the one used by terminfo. If
1398
the <STRONG>smcup</STRONG> sequence will not restore the screen after an
1399
1399
<STRONG>rmcup</STRONG> sequence is output (to the state prior to outputting
1400
1400
<STRONG>rmcup</STRONG>), specify <STRONG>nrrmc</STRONG>.
1401
1401
1402
1402
1403
1403
<STRONG>Area</STRONG> <STRONG>Clears</STRONG>
1404
1404
If the terminal can clear from the current position to the
1405
end of the line, leaving the cursor where it is, this
1405
end of the line, leaving the cursor where it is, this
1406
1406
should be given as <STRONG>el</STRONG>. If the terminal can clear from the
1407
beginning of the line to the current position inclusive,
1408
leaving the cursor where it is, this should be given as
1409
<STRONG>el1</STRONG>. If the terminal can clear from the current position
1410
to the end of the display, then this should be given as
1411
<STRONG>ed</STRONG>. <STRONG>Ed</STRONG> is only defined from the first column of a line.
1412
(Thus, it can be simulated by a request to delete a large
1407
beginning of the line to the current position inclusive,
1408
leaving the cursor where it is, this should be given as
1409
<STRONG>el1</STRONG>. If the terminal can clear from the current position
1410
to the end of the display, then this should be given as
1411
<STRONG>ed</STRONG>. <STRONG>Ed</STRONG> is only defined from the first column of a line.
1412
(Thus, it can be simulated by a request to delete a large
1413
1413
number of lines, if a true <STRONG>ed</STRONG> is not available.)
1414
1414
1415
1415
1416
1416
<STRONG>Insert/delete</STRONG> <STRONG>line</STRONG> <STRONG>and</STRONG> <STRONG>vertical</STRONG> <STRONG>motions</STRONG>
1417
If the terminal can open a new blank line before the line
1418
where the cursor is, this should be given as <STRONG>il1</STRONG>; this is
1419
done only from the first position of a line. The cursor
1417
If the terminal can open a new blank line before the line
1418
where the cursor is, this should be given as <STRONG>il1</STRONG>; this is
1419
done only from the first position of a line. The cursor
1420
1420
must then appear on the newly blank line. If the terminal
1421
can delete the line which the cursor is on, then this
1422
should be given as <STRONG>dl1</STRONG>; this is done only from the first
1423
position on the line to be deleted. Versions of <STRONG>il1</STRONG> and
1424
<STRONG>dl1</STRONG> which take a single parameter and insert or delete
1421
can delete the line which the cursor is on, then this
1422
should be given as <STRONG>dl1</STRONG>; this is done only from the first
1423
position on the line to be deleted. Versions of <STRONG>il1</STRONG> and
1424
<STRONG>dl1</STRONG> which take a single parameter and insert or delete
1425
1425
that many lines can be given as <STRONG>il</STRONG> and <STRONG>dl</STRONG>.
1426
1426
1427
If the terminal has a settable scrolling region (like the
1428
vt100) the command to set this can be described with the
1429
<STRONG>csr</STRONG> capability, which takes two parameters: the top and
1427
If the terminal has a settable scrolling region (like the
1428
vt100) the command to set this can be described with the
1429
<STRONG>csr</STRONG> capability, which takes two parameters: the top and
1430
1430
bottom lines of the scrolling region. The cursor position
1431
1431
is, alas, undefined after using this command.
1432
1432
1433
It is possible to get the effect of insert or delete line
1433
It is possible to get the effect of insert or delete line
1434
1434
using <STRONG>csr</STRONG> on a properly chosen region; the <STRONG>sc</STRONG> and <STRONG>rc</STRONG> (save
1435
and restore cursor) commands may be useful for ensuring
1436
that your synthesized insert/delete string does not move
1437
the cursor. (Note that the <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> library does this
1438
synthesis automatically, so you need not compose
1435
and restore cursor) commands may be useful for ensuring
1436
that your synthesized insert/delete string does not move
1437
the cursor. (Note that the <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> library does this
1438
synthesis automatically, so you need not compose
1439
1439
insert/delete strings for an entry with <STRONG>csr</STRONG>).
1440
1440
1441
1441
Yet another way to construct insert and delete might be to
1442
use a combination of index with the memory-lock feature
1443
found on some terminals (like the HP-700/90 series, which
1442
use a combination of index with the memory-lock feature
1443
found on some terminals (like the HP-700/90 series, which
1444
1444
however also has insert/delete).
1445
1445
1446
Inserting lines at the top or bottom of the screen can
1447
also be done using <STRONG>ri</STRONG> or <STRONG>ind</STRONG> on many terminals without a
1448
true insert/delete line, and is often faster even on
1449
terminals with those features.
1446
Inserting lines at the top or bottom of the screen can
1447
also be done using <STRONG>ri</STRONG> or <STRONG>ind</STRONG> on many terminals without a
1448
true insert/delete line, and is often faster even on ter-
1449
minals with those features.
1450
1450
1451
The boolean <STRONG>non_dest_scroll_region</STRONG> should be set if each
1452
scrolling window is effectively a view port on a screen-
1453
sized canvas. To test for this capability, create a
1454
scrolling region in the middle of the screen, write some-
1455
thing to the bottom line, move the cursor to the top of
1451
The boolean <STRONG>non_dest_scroll_region</STRONG> should be set if each
1452
scrolling window is effectively a view port on a screen-
1453
sized canvas. To test for this capability, create a
1454
scrolling region in the middle of the screen, write some-
1455
thing to the bottom line, move the cursor to the top of
1456
1456
the region, and do <STRONG>ri</STRONG> followed by <STRONG>dl1</STRONG> or <STRONG>ind</STRONG>. If the data
1457
scrolled off the bottom of the region by the <STRONG>ri</STRONG> re-
1458
appears, then scrolling is non-destructive. System V and
1459
XSI Curses expect that <STRONG>ind</STRONG>, <STRONG>ri</STRONG>, <STRONG>indn</STRONG>, and <STRONG>rin</STRONG> will simu-
1460
late destructive scrolling; their documentation cautions
1461
you not to define <STRONG>csr</STRONG> unless this is true. This <STRONG>curses</STRONG>
1457
scrolled off the bottom of the region by the <STRONG>ri</STRONG> re-
1458
appears, then scrolling is non-destructive. System V and
1459
XSI Curses expect that <STRONG>ind</STRONG>, <STRONG>ri</STRONG>, <STRONG>indn</STRONG>, and <STRONG>rin</STRONG> will simu-
1460
late destructive scrolling; their documentation cautions
1461
you not to define <STRONG>csr</STRONG> unless this is true. This <STRONG>curses</STRONG>
1462
1462
implementation is more liberal and will do explicit erases
1463
1463
after scrolling if <STRONG>ndstr</STRONG> is defined.
1464
1464
1465
1465
If the terminal has the ability to define a window as part
1466
of memory, which all commands affect, it should be given
1466
of memory, which all commands affect, it should be given
1467
1467
as the parameterized string <STRONG>wind</STRONG>. The four parameters are
1468
the starting and ending lines in memory and the starting
1468
the starting and ending lines in memory and the starting
1469
1469
and ending columns in memory, in that order.
1470
1470
1471
If the terminal can retain display memory above, then the
1472
<STRONG>da</STRONG> capability should be given; if display memory can be
1473
retained below, then <STRONG>db</STRONG> should be given. These indicate
1474
that deleting a line or scrolling may bring non-blank
1475
lines up from below or that scrolling back with <STRONG>ri</STRONG> may
1471
If the terminal can retain display memory above, then the
1472
<STRONG>da</STRONG> capability should be given; if display memory can be
1473
retained below, then <STRONG>db</STRONG> should be given. These indicate
1474
that deleting a line or scrolling may bring non-blank
1475
lines up from below or that scrolling back with <STRONG>ri</STRONG> may
1476
1476
bring down non-blank lines.
1477
1477
1478
1478
1479
1479
<STRONG>Insert/Delete</STRONG> <STRONG>Character</STRONG>
1480
There are two basic kinds of intelligent terminals with
1481
respect to insert/delete character which can be described
1482
using <EM>terminfo.</EM> The most common insert/delete character
1483
operations affect only the characters on the current line
1484
and shift characters off the end of the line rigidly.
1485
Other terminals, such as the Concept 100 and the Perkin
1486
Elmer Owl, make a distinction between typed and untyped
1487
blanks on the screen, shifting upon an insert or delete
1488
only to an untyped blank on the screen which is either
1489
eliminated, or expanded to two untyped blanks. You can
1490
determine the kind of terminal you have by clearing the
1491
screen and then typing text separated by cursor motions.
1492
Type "abc def" using local cursor motions (not spaces)
1480
There are two basic kinds of intelligent terminals with
1481
respect to insert/delete character which can be described
1482
using <EM>terminfo.</EM> The most common insert/delete character
1483
operations affect only the characters on the current line
1484
and shift characters off the end of the line rigidly.
1485
Other terminals, such as the Concept 100 and the Perkin
1486
Elmer Owl, make a distinction between typed and untyped
1487
blanks on the screen, shifting upon an insert or delete
1488
only to an untyped blank on the screen which is either
1489
eliminated, or expanded to two untyped blanks. You can
1490
determine the kind of terminal you have by clearing the
1491
screen and then typing text separated by cursor motions.
1492
Type "abc def" using local cursor motions (not spaces)
1493
1493
between the "abc" and the "def". Then position the cursor
1494
before the "abc" and put the terminal in insert mode. If
1495
typing characters causes the rest of the line to shift
1494
before the "abc" and put the terminal in insert mode. If
1495
typing characters causes the rest of the line to shift
1496
1496
rigidly and characters to fall off the end, then your ter-
1497
minal does not distinguish between blanks and untyped
1498
positions. If the "abc" shifts over to the "def" which
1499
then move together around the end of the current line and
1500
onto the next as you insert, you have the second type of
1501
terminal, and should give the capability <STRONG>in</STRONG>, which stands
1497
minal does not distinguish between blanks and untyped
1498
positions. If the "abc" shifts over to the "def" which
1499
then move together around the end of the current line and
1500
onto the next as you insert, you have the second type of
1501
terminal, and should give the capability <STRONG>in</STRONG>, which stands
1502
1502
for "insert null". While these are two logically separate
1503
attributes (one line versus multi-line insert mode, and
1504
special treatment of untyped spaces) we have seen no ter-
1503
attributes (one line versus multi-line insert mode, and
1504
special treatment of untyped spaces) we have seen no ter-
1505
1505
minals whose insert mode cannot be described with the sin-
1506
1506
gle attribute.
1507
1507
1508
Terminfo can describe both terminals which have an insert
1508
Terminfo can describe both terminals which have an insert
1509
1509
mode, and terminals which send a simple sequence to open a
1510
blank position on the current line. Give as <STRONG>smir</STRONG> the
1511
sequence to get into insert mode. Give as <STRONG>rmir</STRONG> the
1512
sequence to leave insert mode. Now give as <STRONG>ich1</STRONG> any
1510
blank position on the current line. Give as <STRONG>smir</STRONG> the
1511
sequence to get into insert mode. Give as <STRONG>rmir</STRONG> the
1512
sequence to leave insert mode. Now give as <STRONG>ich1</STRONG> any
1513
1513
sequence needed to be sent just before sending the charac-
1514
ter to be inserted. Most terminals with a true insert
1515
mode will not give <STRONG>ich1</STRONG>; terminals which send a sequence
1514
ter to be inserted. Most terminals with a true insert
1515
mode will not give <STRONG>ich1</STRONG>; terminals which send a sequence
1516
1516
to open a screen position should give it here.
1517
1517
1518
If your terminal has both, insert mode is usually prefer-
1519
able to <STRONG>ich1</STRONG>. Technically, you should not give both
1520
unless the terminal actually requires both to be used in
1521
combination. Accordingly, some non-curses applications
1522
get confused if both are present; the symptom is doubled
1518
If your terminal has both, insert mode is usually prefer-
1519
able to <STRONG>ich1</STRONG>. Technically, you should not give both
1520
unless the terminal actually requires both to be used in
1521
combination. Accordingly, some non-curses applications
1522
get confused if both are present; the symptom is doubled
1523
1523
characters in an update using insert. This requirement is
1524
1524
now rare; most <STRONG>ich</STRONG> sequences do not require previous smir,
1525
1525
and most smir insert modes do not require <STRONG>ich1</STRONG> before each
1526
character. Therefore, the new <STRONG>curses</STRONG> actually assumes
1527
this is the case and uses either <STRONG>rmir</STRONG>/<STRONG>smir</STRONG> or <STRONG>ich</STRONG>/<STRONG>ich1</STRONG> as
1526
character. Therefore, the new <STRONG>curses</STRONG> actually assumes
1527
this is the case and uses either <STRONG>rmir</STRONG>/<STRONG>smir</STRONG> or <STRONG>ich</STRONG>/<STRONG>ich1</STRONG> as
1528
1528
appropriate (but not both). If you have to write an entry
1529
to be used under new curses for a terminal old enough to
1529
to be used under new curses for a terminal old enough to
1530
1530
need both, include the <STRONG>rmir</STRONG>/<STRONG>smir</STRONG> sequences in <STRONG>ich1</STRONG>.
1531
1531
1532
1532
If post insert padding is needed, give this as a number of
1533
milliseconds in <STRONG>ip</STRONG> (a string option). Any other sequence
1534
which may need to be sent after an insert of a single
1533
milliseconds in <STRONG>ip</STRONG> (a string option). Any other sequence
1534
which may need to be sent after an insert of a single
1535
1535
character may also be given in <STRONG>ip</STRONG>. If your terminal needs
1536
1536
both to be placed into an `insert mode' and a special code
1537
to precede each inserted character, then both <STRONG>smir</STRONG>/<STRONG>rmir</STRONG>
1538
and <STRONG>ich1</STRONG> can be given, and both will be used. The <STRONG>ich</STRONG>
1537
to precede each inserted character, then both <STRONG>smir</STRONG>/<STRONG>rmir</STRONG>
1538
and <STRONG>ich1</STRONG> can be given, and both will be used. The <STRONG>ich</STRONG>
1539
1539
capability, with one parameter, <EM>n</EM>, will repeat the effects
1540
1540
of <STRONG>ich1</STRONG> <EM>n</EM> times.
1541
1541
1542
1542
If padding is necessary between characters typed while not
1543
in insert mode, give this as a number of milliseconds
1543
in insert mode, give this as a number of milliseconds
1544
1544
padding in <STRONG>rmp</STRONG>.
1545
1545
1546
It is occasionally necessary to move around while in
1547
insert mode to delete characters on the same line (e.g.,
1548
if there is a tab after the insertion position). If your
1549
terminal allows motion while in insert mode you can give
1550
the capability <STRONG>mir</STRONG> to speed up inserting in this case.
1551
Omitting <STRONG>mir</STRONG> will affect only speed. Some terminals
1546
It is occasionally necessary to move around while in
1547
insert mode to delete characters on the same line (e.g.,
1548
if there is a tab after the insertion position). If your
1549
terminal allows motion while in insert mode you can give
1550
the capability <STRONG>mir</STRONG> to speed up inserting in this case.
1551
Omitting <STRONG>mir</STRONG> will affect only speed. Some terminals
1552
1552
(notably Datamedia's) must not have <STRONG>mir</STRONG> because of the way
1553
1553
their insert mode works.
1554
1554
1555
Finally, you can specify <STRONG>dch1</STRONG> to delete a single charac-
1556
ter, <STRONG>dch</STRONG> with one parameter, <EM>n</EM>, to delete <EM>n</EM> <EM>characters,</EM>
1557
and delete mode by giving <STRONG>smdc</STRONG> and <STRONG>rmdc</STRONG> to enter and exit
1558
delete mode (any mode the terminal needs to be placed in
1555
Finally, you can specify <STRONG>dch1</STRONG> to delete a single charac-
1556
ter, <STRONG>dch</STRONG> with one parameter, <EM>n</EM>, to delete <EM>n</EM> <EM>characters,</EM>
1557
and delete mode by giving <STRONG>smdc</STRONG> and <STRONG>rmdc</STRONG> to enter and exit
1558
delete mode (any mode the terminal needs to be placed in
1559
1559
for <STRONG>dch1</STRONG> to work).
1560
1560
1561
A command to erase <EM>n</EM> characters (equivalent to outputting
1562
<EM>n</EM> blanks without moving the cursor) can be given as <STRONG>ech</STRONG>
1561
A command to erase <EM>n</EM> characters (equivalent to outputting
1562
<EM>n</EM> blanks without moving the cursor) can be given as <STRONG>ech</STRONG>
1563
1563
with one parameter.
1564
1564
1565
1565
1566
1566
<STRONG>Highlighting,</STRONG> <STRONG>Underlining,</STRONG> <STRONG>and</STRONG> <STRONG>Visible</STRONG> <STRONG>Bells</STRONG>
1567
1567
If your terminal has one or more kinds of display
1568
attributes, these can be represented in a number of dif-
1568
attributes, these can be represented in a number of dif-
1569
1569
ferent ways. You should choose one display form as <EM>stand-</EM>
1570
1570
<EM>out</EM> <EM>mode</EM>, representing a good, high contrast, easy-on-the-
1571
eyes, format for highlighting error messages and other
1572
attention getters. (If you have a choice, reverse video
1573
plus half-bright is good, or reverse video alone.) The
1574
sequences to enter and exit standout mode are given as
1575
<STRONG>smso</STRONG> and <STRONG>rmso</STRONG>, respectively. If the code to change into
1576
or out of standout mode leaves one or even two blank
1577
spaces on the screen, as the TVI 912 and Teleray 1061 do,
1571
eyes, format for highlighting error messages and other
1572
attention getters. (If you have a choice, reverse video
1573
plus half-bright is good, or reverse video alone.) The
1574
sequences to enter and exit standout mode are given as
1575
<STRONG>smso</STRONG> and <STRONG>rmso</STRONG>, respectively. If the code to change into
1576
or out of standout mode leaves one or even two blank
1577
spaces on the screen, as the TVI 912 and Teleray 1061 do,
1578
1578
then <STRONG>xmc</STRONG> should be given to tell how many spaces are left.
1579
1579
1580
Codes to begin underlining and end underlining can be
1581
given as <STRONG>smul</STRONG> and <STRONG>rmul</STRONG> respectively. If the terminal has
1582
a code to underline the current character and move the
1580
Codes to begin underlining and end underlining can be
1581
given as <STRONG>smul</STRONG> and <STRONG>rmul</STRONG> respectively. If the terminal has
1582
a code to underline the current character and move the
1583
1583
cursor one space to the right, such as the Microterm Mime,
1584
1584
this can be given as <STRONG>uc</STRONG>.
1585
1585
1586
Other capabilities to enter various highlighting modes
1587
include <STRONG>blink</STRONG> (blinking) <STRONG>bold</STRONG> (bold or extra bright) <STRONG>dim</STRONG>
1588
(dim or half-bright) <STRONG>invis</STRONG> (blanking or invisible text)
1589
<STRONG>prot</STRONG> (protected) <STRONG>rev</STRONG> (reverse video) <STRONG>sgr0</STRONG> (turn off <EM>all</EM>
1590
attribute modes) <STRONG>smacs</STRONG> (enter alternate character set
1591
mode) and <STRONG>rmacs</STRONG> (exit alternate character set mode).
1592
Turning on any of these modes singly may or may not turn
1586
Other capabilities to enter various highlighting modes
1587
include <STRONG>blink</STRONG> (blinking) <STRONG>bold</STRONG> (bold or extra bright) <STRONG>dim</STRONG>
1588
(dim or half-bright) <STRONG>invis</STRONG> (blanking or invisible text)
1589
<STRONG>prot</STRONG> (protected) <STRONG>rev</STRONG> (reverse video) <STRONG>sgr0</STRONG> (turn off <EM>all</EM>
1590
attribute modes) <STRONG>smacs</STRONG> (enter alternate character set
1591
mode) and <STRONG>rmacs</STRONG> (exit alternate character set mode).
1592
Turning on any of these modes singly may or may not turn
1593
1593
off other modes.
1594
1594
1595
If there is a sequence to set arbitrary combinations of
1596
modes, this should be given as <STRONG>sgr</STRONG> (set attributes), tak-
1597
ing 9 parameters. Each parameter is either 0 or nonzero,
1595
If there is a sequence to set arbitrary combinations of
1596
modes, this should be given as <STRONG>sgr</STRONG> (set attributes), tak-
1597
ing 9 parameters. Each parameter is either 0 or nonzero,
1598
1598
as the corresponding attribute is on or off. The 9 param-
1599
eters are, in order: standout, underline, reverse, blink,
1600
dim, bold, blank, protect, alternate character set. Not
1601
all modes need be supported by <STRONG>sgr</STRONG>, only those for which
1599
eters are, in order: standout, underline, reverse, blink,
1600
dim, bold, blank, protect, alternate character set. Not
1601
all modes need be supported by <STRONG>sgr</STRONG>, only those for which
1602
1602
corresponding separate attribute commands exist.
1603
1603
1604
1604
For example, the DEC vt220 supports most of the modes:
1617
1617
p8 protect not used
1618
1618
p9 altcharset ^O (off) ^N (on)
1619
1619
1620
We begin each escape sequence by turning off any existing
1621
modes, since there is no quick way to determine whether
1620
We begin each escape sequence by turning off any existing
1621
modes, since there is no quick way to determine whether
1622
1622
they are active. Standout is set up to be the combination
1623
of reverse and bold. The vt220 terminal has a protect
1624
mode, though it is not commonly used in sgr because it
1625
protects characters on the screen from the host's era-
1626
sures. The altcharset mode also is different in that it
1627
is either ^O or ^N, depending on whether it is off or on.
1628
If all modes are turned on, the resulting sequence is
1623
of reverse and bold. The vt220 terminal has a protect
1624
mode, though it is not commonly used in sgr because it
1625
protects characters on the screen from the host's era-
1626
sures. The altcharset mode also is different in that it
1627
is either ^O or ^N, depending on whether it is off or on.
1628
If all modes are turned on, the resulting sequence is
1629
1629
\E[0;1;4;5;7;8m^N.
1630
1630
1631
Some sequences are common to different modes. For exam-
1632
ple, ;7 is output when either p1 or p3 is true, that is,
1631
Some sequences are common to different modes. For exam-
1632
ple, ;7 is output when either p1 or p3 is true, that is,
1633
1633
if either standout or reverse modes are turned on.
1634
1634
1635
Writing out the above sequences, along with their depen-
1635
Writing out the above sequences, along with their depen-
1636
1636
dencies yields
1637
1637
1638
1638
1643
1643
;4 if p2 %?%p2%|%t;4%;
1644
1644
;5 if p4 %?%p4%|%t;5%;
1645
1645
;7 if p1 or p3 %?%p1%p3%|%t;7%;
1646
1647
1646
;8 if p7 %?%p7%|%t;8%;
1647
1648
1648
m always m
1649
1649
^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%;
1650
1650
1653
1653
sgr=\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;
1654
1654
%?%p4%t;5%;%?%p7%t;8%;m%?%p9%t\016%e\017%;,
1655
1655
1656
Remember that if you specify sgr, you must also specify
1657
sgr0. Also, some implementations rely on sgr being given
1658
if sgr0 is, Not all terminfo entries necessarily have an
1659
sgr string, however. Many terminfo entries are derived
1660
from termcap entries which have no sgr string. The only
1661
drawback to adding an sgr string is that termcap also
1662
assumes that sgr0 does not exit alternate character set
1656
Remember that if you specify sgr, you must also specify
1657
sgr0. Also, some implementations rely on sgr being given
1658
if sgr0 is, Not all terminfo entries necessarily have an
1659
sgr string, however. Many terminfo entries are derived
1660
from termcap entries which have no sgr string. The only
1661
drawback to adding an sgr string is that termcap also
1662
assumes that sgr0 does not exit alternate character set
1663
1663
mode.
1664
1664
1665
Terminals with the ``magic cookie'' glitch (<STRONG>xmc</STRONG>) deposit
1666
special ``cookies'' when they receive mode-setting
1667
sequences, which affect the display algorithm rather than
1668
having extra bits for each character. Some terminals,
1669
such as the HP 2621, automatically leave standout mode
1670
when they move to a new line or the cursor is addressed.
1671
Programs using standout mode should exit standout mode
1672
before moving the cursor or sending a newline, unless the
1673
<STRONG>msgr</STRONG> capability, asserting that it is safe to move in
1665
Terminals with the ``magic cookie'' glitch (<STRONG>xmc</STRONG>) deposit
1666
special ``cookies'' when they receive mode-setting
1667
sequences, which affect the display algorithm rather than
1668
having extra bits for each character. Some terminals,
1669
such as the HP 2621, automatically leave standout mode
1670
when they move to a new line or the cursor is addressed.
1671
Programs using standout mode should exit standout mode
1672
before moving the cursor or sending a newline, unless the
1673
<STRONG>msgr</STRONG> capability, asserting that it is safe to move in
1674
1674
standout mode, is present.
1675
1675
1676
If the terminal has a way of flashing the screen to indi-
1677
cate an error quietly (a bell replacement) then this can
1676
If the terminal has a way of flashing the screen to indi-
1677
cate an error quietly (a bell replacement) then this can
1678
1678
be given as <STRONG>flash</STRONG>; it must not move the cursor.
1679
1679
1680
If the cursor needs to be made more visible than normal
1680
If the cursor needs to be made more visible than normal
1681
1681
when it is not on the bottom line (to make, for example, a
1682
non-blinking underline into an easier to find block or
1682
non-blinking underline into an easier to find block or
1683
1683
blinking underline) give this sequence as <STRONG>cvvis</STRONG>. If there
1684
is a way to make the cursor completely invisible, give
1684
is a way to make the cursor completely invisible, give
1685
1685
that as <STRONG>civis</STRONG>. The capability <STRONG>cnorm</STRONG> should be given which
1686
1686
undoes the effects of both of these modes.
1687
1687
1688
1688
If your terminal correctly generates underlined characters
1689
(with no special codes needed) even though it does not
1690
overstrike, then you should give the capability <STRONG>ul</STRONG>. If a
1691
character overstriking another leaves both characters on
1689
(with no special codes needed) even though it does not
1690
overstrike, then you should give the capability <STRONG>ul</STRONG>. If a
1691
character overstriking another leaves both characters on
1692
1692
the screen, specify the capability <STRONG>os</STRONG>. If overstrikes are
1693
erasable with a blank, then this should be indicated by
1693
erasable with a blank, then this should be indicated by
1694
1694
giving <STRONG>eo</STRONG>.
1695
1695
1696
1696
1697
1697
<STRONG>Keypad</STRONG> <STRONG>and</STRONG> <STRONG>Function</STRONG> <STRONG>Keys</STRONG>
1698
1698
If the terminal has a keypad that transmits codes when the
1699
keys are pressed, this information can be given. Note
1699
keys are pressed, this information can be given. Note
1700
1700
that it is not possible to handle terminals where the key-
1701
1701
pad only works in local (this applies, for example, to the
1702
unshifted HP 2621 keys). If the keypad can be set to
1703
transmit or not transmit, give these codes as <STRONG>smkx</STRONG> and
1702
unshifted HP 2621 keys). If the keypad can be set to
1703
transmit or not transmit, give these codes as <STRONG>smkx</STRONG> and
1704
1704
<STRONG>rmkx</STRONG>. Otherwise the keypad is assumed to always transmit.
1705
The codes sent by the left arrow, right arrow, up arrow,
1706
down arrow, and home keys can be given as <STRONG>kcub1,</STRONG> <STRONG>kcuf1,</STRONG>
1707
<STRONG>kcuu1,</STRONG> <STRONG>kcud1,</STRONG> and <STRONG>khome</STRONG> respectively. If there are func-
1708
tion keys such as f0, f1, ..., f10, the codes they send
1709
can be given as <STRONG>kf0,</STRONG> <STRONG>kf1,</STRONG> <STRONG>...,</STRONG> <STRONG>kf10</STRONG>. If these keys have
1710
labels other than the default f0 through f10, the labels
1711
can be given as <STRONG>lf0,</STRONG> <STRONG>lf1,</STRONG> <STRONG>...,</STRONG> <STRONG>lf10</STRONG>. The codes transmit-
1712
ted by certain other special keys can be given: <STRONG>kll</STRONG> (home
1713
down), <STRONG>kbs</STRONG> (backspace), <STRONG>ktbc</STRONG> (clear all tabs), <STRONG>kctab</STRONG>
1705
The codes sent by the left arrow, right arrow, up arrow,
1706
down arrow, and home keys can be given as <STRONG>kcub1,</STRONG> <STRONG>kcuf1,</STRONG>
1707
<STRONG>kcuu1,</STRONG> <STRONG>kcud1,</STRONG> and <STRONG>khome</STRONG> respectively. If there are func-
1708
tion keys such as f0, f1, ..., f10, the codes they send
1709
can be given as <STRONG>kf0,</STRONG> <STRONG>kf1,</STRONG> <STRONG>...,</STRONG> <STRONG>kf10</STRONG>. If these keys have
1710
labels other than the default f0 through f10, the labels
1711
can be given as <STRONG>lf0,</STRONG> <STRONG>lf1,</STRONG> <STRONG>...,</STRONG> <STRONG>lf10</STRONG>. The codes transmit-
1712
ted by certain other special keys can be given: <STRONG>kll</STRONG> (home
1713
down), <STRONG>kbs</STRONG> (backspace), <STRONG>ktbc</STRONG> (clear all tabs), <STRONG>kctab</STRONG>
1714
1714
(clear the tab stop in this column), <STRONG>kclr</STRONG> (clear screen or
1715
erase key), <STRONG>kdch1</STRONG> (delete character), <STRONG>kdl1</STRONG> (delete line),
1716
<STRONG>krmir</STRONG> (exit insert mode), <STRONG>kel</STRONG> (clear to end of line), <STRONG>ked</STRONG>
1715
erase key), <STRONG>kdch1</STRONG> (delete character), <STRONG>kdl1</STRONG> (delete line),
1716
<STRONG>krmir</STRONG> (exit insert mode), <STRONG>kel</STRONG> (clear to end of line), <STRONG>ked</STRONG>
1717
1717
(clear to end of screen), <STRONG>kich1</STRONG> (insert character or enter
1718
insert mode), <STRONG>kil1</STRONG> (insert line), <STRONG>knp</STRONG> (next page), <STRONG>kpp</STRONG>
1719
(previous page), <STRONG>kind</STRONG> (scroll forward/down), <STRONG>kri</STRONG> (scroll
1720
backward/up), <STRONG>khts</STRONG> (set a tab stop in this column). In
1718
insert mode), <STRONG>kil1</STRONG> (insert line), <STRONG>knp</STRONG> (next page), <STRONG>kpp</STRONG>
1719
(previous page), <STRONG>kind</STRONG> (scroll forward/down), <STRONG>kri</STRONG> (scroll
1720
backward/up), <STRONG>khts</STRONG> (set a tab stop in this column). In
1721
1721
addition, if the keypad has a 3 by 3 array of keys includ-
1722
ing the four arrow keys, the other five keys can be given
1723
as <STRONG>ka1</STRONG>, <STRONG>ka3</STRONG>, <STRONG>kb2</STRONG>, <STRONG>kc1</STRONG>, and <STRONG>kc3</STRONG>. These keys are useful
1722
ing the four arrow keys, the other five keys can be given
1723
as <STRONG>ka1</STRONG>, <STRONG>ka3</STRONG>, <STRONG>kb2</STRONG>, <STRONG>kc1</STRONG>, and <STRONG>kc3</STRONG>. These keys are useful
1724
1724
when the effects of a 3 by 3 directional pad are needed.
1725
1725
1726
Strings to program function keys can be given as <STRONG>pfkey</STRONG>,
1727
<STRONG>pfloc</STRONG>, and <STRONG>pfx</STRONG>. A string to program screen labels should
1728
be specified as <STRONG>pln</STRONG>. Each of these strings takes two
1729
parameters: the function key number to program (from 0 to
1730
10) and the string to program it with. Function key num-
1731
bers out of this range may program undefined keys in a
1732
terminal dependent manner. The difference between the
1733
capabilities is that <STRONG>pfkey</STRONG> causes pressing the given key
1734
to be the same as the user typing the given string; <STRONG>pfloc</STRONG>
1726
Strings to program function keys can be given as <STRONG>pfkey</STRONG>,
1727
<STRONG>pfloc</STRONG>, and <STRONG>pfx</STRONG>. A string to program screen labels should
1728
be specified as <STRONG>pln</STRONG>. Each of these strings takes two
1729
parameters: the function key number to program (from 0 to
1730
10) and the string to program it with. Function key num-
1731
bers out of this range may program undefined keys in a
1732
terminal dependent manner. The difference between the
1733
capabilities is that <STRONG>pfkey</STRONG> causes pressing the given key
1734
to be the same as the user typing the given string; <STRONG>pfloc</STRONG>
1735
1735
causes the string to be executed by the terminal in local;
1736
and <STRONG>pfx</STRONG> causes the string to be transmitted to the com-
1736
and <STRONG>pfx</STRONG> causes the string to be transmitted to the com-
1737
1737
puter.
1738
1738
1739
1739
The capabilities <STRONG>nlab</STRONG>, <STRONG>lw</STRONG> and <STRONG>lh</STRONG> define the number of pro-
1740
grammable screen labels and their width and height. If
1741
there are commands to turn the labels on and off, give
1742
them in <STRONG>smln</STRONG> and <STRONG>rmln</STRONG>. <STRONG>smln</STRONG> is normally output after one
1740
grammable screen labels and their width and height. If
1741
there are commands to turn the labels on and off, give
1742
them in <STRONG>smln</STRONG> and <STRONG>rmln</STRONG>. <STRONG>smln</STRONG> is normally output after one
1743
1743
or more pln sequences to make sure that the change becomes
1744
1744
visible.
1745
1745
1746
1746
1747
1747
<STRONG>Tabs</STRONG> <STRONG>and</STRONG> <STRONG>Initialization</STRONG>
1748
If the terminal has hardware tabs, the command to advance
1749
to the next tab stop can be given as <STRONG>ht</STRONG> (usually control
1750
I). A ``back-tab'' command which moves leftward to the
1748
If the terminal has hardware tabs, the command to advance
1749
to the next tab stop can be given as <STRONG>ht</STRONG> (usually control
1750
I). A ``back-tab'' command which moves leftward to the
1751
1751
preceding tab stop can be given as <STRONG>cbt</STRONG>. By convention, if
1752
the teletype modes indicate that tabs are being expanded
1753
by the computer rather than being sent to the terminal,
1754
programs should not use <STRONG>ht</STRONG> or <STRONG>cbt</STRONG> even if they are
1755
present, since the user may not have the tab stops prop-
1756
erly set. If the terminal has hardware tabs which are
1757
initially set every <EM>n</EM> spaces when the terminal is powered
1758
up, the numeric parameter <STRONG>it</STRONG> is given, showing the number
1759
of spaces the tabs are set to. This is normally used by
1760
the <EM>tset</EM> command to determine whether to set the mode for
1761
hardware tab expansion, and whether to set the tab stops.
1762
If the terminal has tab stops that can be saved in non-
1763
volatile memory, the terminfo description can assume that
1752
the teletype modes indicate that tabs are being expanded
1753
by the computer rather than being sent to the terminal,
1754
programs should not use <STRONG>ht</STRONG> or <STRONG>cbt</STRONG> even if they are
1755
present, since the user may not have the tab stops prop-
1756
erly set. If the terminal has hardware tabs which are
1757
initially set every <EM>n</EM> spaces when the terminal is powered
1758
up, the numeric parameter <STRONG>it</STRONG> is given, showing the number
1759
of spaces the tabs are set to. This is normally used by
1760
the <EM>tset</EM> command to determine whether to set the mode for
1761
hardware tab expansion, and whether to set the tab stops.
1762
If the terminal has tab stops that can be saved in non-
1763
volatile memory, the terminfo description can assume that
1764
1764
they are properly set.
1765
1765
1766
Other capabilities include <STRONG>is1</STRONG>, <STRONG>is2</STRONG>, and <STRONG>is3</STRONG>, initializa-
1767
tion strings for the terminal, <STRONG>iprog</STRONG>, the path name of a
1768
program to be run to initialize the terminal, and <STRONG>if</STRONG>, the
1769
name of a file containing long initialization strings.
1770
These strings are expected to set the terminal into modes
1771
consistent with the rest of the terminfo description.
1766
Other capabilities include <STRONG>is1</STRONG>, <STRONG>is2</STRONG>, and <STRONG>is3</STRONG>, initializa-
1767
tion strings for the terminal, <STRONG>iprog</STRONG>, the path name of a
1768
program to be run to initialize the terminal, and <STRONG>if</STRONG>, the
1769
name of a file containing long initialization strings.
1770
These strings are expected to set the terminal into modes
1771
consistent with the rest of the terminfo description.
1772
1772
They are normally sent to the terminal, by the <EM>init</EM> option
1773
of the <EM>tput</EM> program, each time the user logs in. They
1774
will be printed in the following order: run the program
1775
<STRONG>iprog</STRONG>; output <STRONG>is1</STRONG>; <STRONG>is2</STRONG>; set the margins using <STRONG>mgc</STRONG>, <STRONG>smgl</STRONG>
1776
and <STRONG>smgr</STRONG>; set tabs using <STRONG>tbc</STRONG> and <STRONG>hts</STRONG>; print the file <STRONG>if</STRONG>;
1777
and finally output <STRONG>is3</STRONG>.
1773
of the <EM>tput</EM> program, each time the user logs in. They
1774
will be printed in the following order:
1775
1776
run the program
1777
<STRONG>iprog</STRONG>
1778
1779
output <STRONG>is1</STRONG> <STRONG>is2</STRONG>
1780
1781
set the margins using
1782
<STRONG>mgc</STRONG>, <STRONG>smgl</STRONG> and <STRONG>smgr</STRONG>
1783
1784
set tabs using
1785
<STRONG>tbc</STRONG> and <STRONG>hts</STRONG>
1786
1787
print the file
1788
<STRONG>if</STRONG>
1789
1790
and finally
1791
output <STRONG>is3</STRONG>.
1778
1792
1779
1793
Most initialization is done with <STRONG>is2</STRONG>. Special terminal
1780
1794
modes can be set up without duplicating strings by putting
1781
1795
the common sequences in <STRONG>is2</STRONG> and special cases in <STRONG>is1</STRONG> and
1782
<STRONG>is3</STRONG>. A pair of sequences that does a harder reset from a
1783
totally unknown state can be analogously given as <STRONG>rs1</STRONG>,
1784
<STRONG>rs2</STRONG>, <STRONG>rf</STRONG>, and <STRONG>rs3</STRONG>, analogous to <STRONG>is2</STRONG> and <STRONG>if</STRONG>. These strings
1785
are output by the <EM>reset</EM> program, which is used when the
1786
terminal gets into a wedged state. Commands are normally
1787
placed in <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG> <STRONG>rs3</STRONG> and <STRONG>rf</STRONG> only if they produce annoy-
1788
ing effects on the screen and are not necessary when log-
1789
ging in. For example, the command to set the vt100 into
1790
80-column mode would normally be part of <STRONG>is2</STRONG>, but it
1791
causes an annoying glitch of the screen and is not nor-
1792
mally needed since the terminal is usually already in 80
1793
column mode.
1796
<STRONG>is3</STRONG>.
1797
1798
A set of sequences that does a harder reset from a totally
1799
unknown state can be given as <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, <STRONG>rf</STRONG> and <STRONG>rs3</STRONG>, analo-
1800
gous to <STRONG>is1</STRONG> <STRONG>,</STRONG> <STRONG>is2</STRONG> <STRONG>,</STRONG> <STRONG>if</STRONG> and <STRONG>is3</STRONG> respectively. These
1801
strings are output by the <EM>reset</EM> program, which is used
1802
when the terminal gets into a wedged state. Commands are
1803
normally placed in <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG> <STRONG>rs3</STRONG> and <STRONG>rf</STRONG> only if they pro-
1804
duce annoying effects on the screen and are not necessary
1805
when logging in. For example, the command to set the
1806
vt100 into 80-column mode would normally be part of <STRONG>is2</STRONG>,
1807
but it causes an annoying glitch of the screen and is not
1808
normally needed since the terminal is usually already in
1809
80 column mode.
1810
1811
The <EM>reset</EM> program writes strings including <STRONG>iprog</STRONG>, etc., in
1812
the same order as the <EM>init</EM> program, using <STRONG>rs1</STRONG>, etc.,
1813
instead of <STRONG>is1</STRONG>, etc. If any of <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, <STRONG>rs3</STRONG>, or <STRONG>rf</STRONG> reset
1814
capability strings are missing, the <EM>reset</EM> program falls
1815
back upon the corresponding initialization capability
1816
string.
1794
1817
1795
1818
If there are commands to set and clear tab stops, they can
1796
be given as <STRONG>tbc</STRONG> (clear all tab stops) and <STRONG>hts</STRONG> (set a tab
1797
stop in the current column of every row). If a more com-
1798
plex sequence is needed to set the tabs than can be
1799
described by this, the sequence can be placed in <STRONG>is2</STRONG> or
1819
be given as <STRONG>tbc</STRONG> (clear all tab stops) and <STRONG>hts</STRONG> (set a tab
1820
stop in the current column of every row). If a more com-
1821
plex sequence is needed to set the tabs than can be
1822
described by this, the sequence can be placed in <STRONG>is2</STRONG> or
1800
1823
<STRONG>if</STRONG>.
1801
1824
1802
1825
<STRONG>Delays</STRONG> <STRONG>and</STRONG> <STRONG>Padding</STRONG>
1803
Many older and slower terminals do not support either
1826
Many older and slower terminals do not support either
1804
1827
XON/XOFF or DTR handshaking, including hard copy terminals
1805
and some very archaic CRTs (including, for example, DEC
1806
VT100s). These may require padding characters after cer-
1828
and some very archaic CRTs (including, for example, DEC
1829
VT100s). These may require padding characters after cer-
1807
1830
tain cursor motions and screen changes.
1808
1831
1809
1832
If the terminal uses xon/xoff handshaking for flow control
1810
(that is, it automatically emits ^S back to the host when
1833
(that is, it automatically emits ^S back to the host when
1811
1834
its input buffers are close to full), set <STRONG>xon</STRONG>. This capa-
1812
bility suppresses the emission of padding. You can also
1813
set it for memory-mapped console devices effectively that
1814
do not have a speed limit. Padding information should
1815
still be included so that routines can make better deci-
1835
bility suppresses the emission of padding. You can also
1836
set it for memory-mapped console devices effectively that
1837
do not have a speed limit. Padding information should
1838
still be included so that routines can make better deci-
1816
1839
sions about relative costs, but actual pad characters will
1817
1840
not be transmitted.
1818
1841
1819
If <STRONG>pb</STRONG> (padding baud rate) is given, padding is suppressed
1820
at baud rates below the value of <STRONG>pb</STRONG>. If the entry has no
1821
padding baud rate, then whether padding is emitted or not
1842
If <STRONG>pb</STRONG> (padding baud rate) is given, padding is suppressed
1843
at baud rates below the value of <STRONG>pb</STRONG>. If the entry has no
1844
padding baud rate, then whether padding is emitted or not
1822
1845
is completely controlled by <STRONG>xon</STRONG>.
1823
1846
1824
If the terminal requires other than a null (zero) charac-
1825
ter as a pad, then this can be given as <STRONG>pad</STRONG>. Only the
1826
first character of the <STRONG>pad</STRONG> string is used.
1847
If the terminal requires other than a null (zero)
1848
character as a pad, then this can be given as <STRONG>pad</STRONG>. Only
1849
the first character of the <STRONG>pad</STRONG> string is used.
1827
1850
1828
1851
1829
1852
<STRONG>Status</STRONG> <STRONG>Lines</STRONG>
1830
Some terminals have an extra `status line' which is not
1831
normally used by software (and thus not counted in the
1853
Some terminals have an extra `status line' which is not
1854
normally used by software (and thus not counted in the
1832
1855
terminal's <STRONG>lines</STRONG> capability).
1833
1856
1834
The simplest case is a status line which is cursor-
1835
addressable but not part of the main scrolling region on
1836
the screen; the Heathkit H19 has a status line of this
1837
kind, as would a 24-line VT100 with a 23-line scrolling
1838
region set up on initialization. This situation is indi-
1857
The simplest case is a status line which is cursor-
1858
addressable but not part of the main scrolling region on
1859
the screen; the Heathkit H19 has a status line of this
1860
kind, as would a 24-line VT100 with a 23-line scrolling
1861
region set up on initialization. This situation is indi-
1839
1862
cated by the <STRONG>hs</STRONG> capability.
1840
1863
1841
1864
Some terminals with status lines need special sequences to
1842
access the status line. These may be expressed as a
1865
access the status line. These may be expressed as a
1843
1866
string with single parameter <STRONG>tsl</STRONG> which takes the cursor to
1844
a given zero-origin column on the status line. The
1845
capability <STRONG>fsl</STRONG> must return to the main-screen cursor posi-
1846
tions before the last <STRONG>tsl</STRONG>. You may need to embed the
1847
string values of <STRONG>sc</STRONG> (save cursor) and <STRONG>rc</STRONG> (restore cursor)
1848
in <STRONG>tsl</STRONG> and <STRONG>fsl</STRONG> to accomplish this.
1867
a given zero-origin column on the status line. The capa-
1868
bility <STRONG>fsl</STRONG> must return to the main-screen cursor positions
1869
before the last <STRONG>tsl</STRONG>. You may need to embed the string
1870
values of <STRONG>sc</STRONG> (save cursor) and <STRONG>rc</STRONG> (restore cursor) in <STRONG>tsl</STRONG>
1871
and <STRONG>fsl</STRONG> to accomplish this.
1849
1872
1850
The status line is normally assumed to be the same width
1851
as the width of the terminal. If this is untrue, you can
1873
The status line is normally assumed to be the same width
1874
as the width of the terminal. If this is untrue, you can
1852
1875
specify it with the numeric capability <STRONG>wsl</STRONG>.
1853
1876
1854
A command to erase or blank the status line may be speci-
1877
A command to erase or blank the status line may be speci-
1855
1878
fied as <STRONG>dsl</STRONG>.
1856
1879
1857
The boolean capability <STRONG>eslok</STRONG> specifies that escape
1880
The boolean capability <STRONG>eslok</STRONG> specifies that escape
1858
1881
sequences, tabs, etc., work ordinarily in the status line.
1859
1882
1860
The <STRONG>ncurses</STRONG> implementation does not yet use any of these
1861
capabilities. They are documented here in case they ever
1883
The <STRONG>ncurses</STRONG> implementation does not yet use any of these
1884
capabilities. They are documented here in case they ever
1862
1885
become important.
1863
1886
1864
1887
1865
1888
<STRONG>Line</STRONG> <STRONG>Graphics</STRONG>
1866
Many terminals have alternate character sets useful for
1867
forms-drawing. Terminfo and <STRONG>curses</STRONG> build in support for
1868
the drawing characters supported by the VT100, with some
1869
characters from the AT&T 4410v1 added. This alternate
1889
Many terminals have alternate character sets useful for
1890
forms-drawing. Terminfo and <STRONG>curses</STRONG> build in support for
1891
the drawing characters supported by the VT100, with some
1892
characters from the AT&T 4410v1 added. This alternate
1870
1893
character set may be specified by the <STRONG>acsc</STRONG> capability.
1871
1894
1872
1895
1888
1911
lantern symbol ACS_LANTERN # i
1889
1912
large plus or crossover ACS_PLUS + n
1890
1913
less-than-or-equal-to ACS_LEQUAL < y
1914
1891
1915
lower left corner ACS_LLCORNER + m
1892
1916
lower right corner ACS_LRCORNER + j
1893
1917
not-equal ACS_NEQUAL ! |
1905
1929
upper right corner ACS_URCORNER + k
1906
1930
vertical line ACS_VLINE | x
1907
1931
1908
The best way to define a new device's graphics set is to
1909
add a column to a copy of this table for your terminal,
1910
giving the character which (when emitted between
1911
<STRONG>smacs</STRONG>/<STRONG>rmacs</STRONG> switches) will be rendered as the correspond-
1912
ing graphic. Then read off the VT100/your terminal char-
1913
acter pairs right to left in sequence; these become the
1932
The best way to define a new device's graphics set is to
1933
add a column to a copy of this table for your terminal,
1934
giving the character which (when emitted between
1935
<STRONG>smacs</STRONG>/<STRONG>rmacs</STRONG> switches) will be rendered as the correspond-
1936
ing graphic. Then read off the VT100/your terminal char-
1937
acter pairs right to left in sequence; these become the
1914
1938
ACSC string.
1915
1939
1916
1940
1917
1941
<STRONG>Color</STRONG> <STRONG>Handling</STRONG>
1918
Most color terminals are either `Tektronix-like' or `HP-
1919
like'. Tektronix-like terminals have a predefined set of
1920
N colors (where N usually 8), and can set character-cell
1942
Most color terminals are either `Tektronix-like' or `HP-
1943
like'. Tektronix-like terminals have a predefined set of
1944
N colors (where N usually 8), and can set character-cell
1921
1945
foreground and background characters independently, mixing
1922
them into N * N color-pairs. On HP-like terminals, the
1946
them into N * N color-pairs. On HP-like terminals, the
1923
1947
use must set each color pair up separately (foreground and
1924
background are not independently settable). Up to M
1925
color-pairs may be set up from 2*M different colors.
1948
background are not independently settable). Up to M
1949
color-pairs may be set up from 2*M different colors.
1926
1950
ANSI-compatible terminals are Tektronix-like.
1927
1951
1928
1952
Some basic color capabilities are independent of the color
1929
1953
method. The numeric capabilities <STRONG>colors</STRONG> and <STRONG>pairs</STRONG> specify
1930
the maximum numbers of colors and color-pairs that can be
1931
displayed simultaneously. The <STRONG>op</STRONG> (original pair) string
1932
resets foreground and background colors to their default
1933
values for the terminal. The <STRONG>oc</STRONG> string resets all colors
1934
or color-pairs to their default values for the terminal.
1935
Some terminals (including many PC terminal emulators)
1936
erase screen areas with the current background color
1937
rather than the power-up default background; these should
1954
the maximum numbers of colors and color-pairs that can be
1955
displayed simultaneously. The <STRONG>op</STRONG> (original pair) string
1956
resets foreground and background colors to their default
1957
values for the terminal. The <STRONG>oc</STRONG> string resets all colors
1958
or color-pairs to their default values for the terminal.
1959
Some terminals (including many PC terminal emulators)
1960
erase screen areas with the current background color
1961
rather than the power-up default background; these should
1938
1962
have the boolean capability <STRONG>bce</STRONG>.
1939
1963
1940
To change the current foreground or background color on a
1941
Tektronix-type terminal, use <STRONG>setaf</STRONG> (set ANSI foreground)
1942
and <STRONG>setab</STRONG> (set ANSI background) or <STRONG>setf</STRONG> (set foreground)
1943
and <STRONG>setb</STRONG> (set background). These take one parameter, the
1964
To change the current foreground or background color on a
1965
Tektronix-type terminal, use <STRONG>setaf</STRONG> (set ANSI foreground)
1966
and <STRONG>setab</STRONG> (set ANSI background) or <STRONG>setf</STRONG> (set foreground)
1967
and <STRONG>setb</STRONG> (set background). These take one parameter, the
1944
1968
color number. The SVr4 documentation describes only
1945
<STRONG>setaf</STRONG>/<STRONG>setab</STRONG>; the XPG4 draft says that "If the terminal
1969
<STRONG>setaf</STRONG>/<STRONG>setab</STRONG>; the XPG4 draft says that "If the terminal
1946
1970
supports ANSI escape sequences to set background and fore-
1947
ground, they should be coded as <STRONG>setaf</STRONG> and <STRONG>setab</STRONG>, respec-
1948
tively. If the terminal supports other escape sequences
1949
to set background and foreground, they should be coded as
1950
<STRONG>setf</STRONG> and <STRONG>setb</STRONG>, respectively. The <EM>vidputs()</EM> function and
1951
the refresh functions use <STRONG>setaf</STRONG> and <STRONG>setab</STRONG> if they are
1971
ground, they should be coded as <STRONG>setaf</STRONG> and <STRONG>setab</STRONG>, respec-
1972
tively. If the terminal supports other escape sequences
1973
to set background and foreground, they should be coded as
1974
<STRONG>setf</STRONG> and <STRONG>setb</STRONG>, respectively. The <EM>vidputs()</EM> function and
1975
the refresh functions use <STRONG>setaf</STRONG> and <STRONG>setab</STRONG> if they are
1952
1976
defined."
1953
1977
1954
The <STRONG>setaf</STRONG>/<STRONG>setab</STRONG> and <STRONG>setf</STRONG>/<STRONG>setb</STRONG> capabilities take a single
1978
The <STRONG>setaf</STRONG>/<STRONG>setab</STRONG> and <STRONG>setf</STRONG>/<STRONG>setb</STRONG> capabilities take a single
1955
1979
numeric argument each. Argument values 0-7 of <STRONG>setaf</STRONG>/<STRONG>setab</STRONG>
1956
are portably defined as follows (the middle column is the
1980
are portably defined as follows (the middle column is the
1957
1981
symbolic #define available in the header for the <STRONG>curses</STRONG> or
1958
<STRONG>ncurses</STRONG> libraries). The terminal hardware is free to map
1959
these as it likes, but the RGB values indicate normal
1982
<STRONG>ncurses</STRONG> libraries). The terminal hardware is free to map
1983
these as it likes, but the RGB values indicate normal
1960
1984
locations in color space.
1961
1985
1962
1986
1970
1994
cyan <STRONG>COLOR_CYAN</STRONG> 6 0,max,max
1971
1995
white <STRONG>COLOR_WHITE</STRONG> 7 max,max,max
1972
1996
1973
The argument values of <STRONG>setf</STRONG>/<STRONG>setb</STRONG> historically correspond
1997
The argument values of <STRONG>setf</STRONG>/<STRONG>setb</STRONG> historically correspond
1974
1998
to a different mapping, i.e.,
1975
1999
1976
1977
2000
<STRONG>Color</STRONG> <STRONG>#define</STRONG> <STRONG>Value</STRONG> <STRONG>RGB</STRONG>
1978
2001
black <STRONG>COLOR_BLACK</STRONG> 0 0, 0, 0
1979
2002
blue <STRONG>COLOR_BLUE</STRONG> 1 0,0,max
1984
2007
yellow <STRONG>COLOR_YELLOW</STRONG> 6 max,max,0
1985
2008
white <STRONG>COLOR_WHITE</STRONG> 7 max,max,max
1986
2009
It is important to not confuse the two sets of color capa-
1987
bilities; otherwise red/blue will be interchanged on the
2010
bilities; otherwise red/blue will be interchanged on the
1988
2011
display.
1989
2012
1990
On an HP-like terminal, use <STRONG>scp</STRONG> with a color-pair number
2013
On an HP-like terminal, use <STRONG>scp</STRONG> with a color-pair number
1991
2014
parameter to set which color pair is current.
1992
2015
1993
On a Tektronix-like terminal, the capability <STRONG>ccc</STRONG> may be
1994
present to indicate that colors can be modified. If so,
2016
On a Tektronix-like terminal, the capability <STRONG>ccc</STRONG> may be
2017
present to indicate that colors can be modified. If so,
1995
2018
the <STRONG>initc</STRONG> capability will take a color number (0 to <STRONG>colors</STRONG>
1996
- 1)and three more parameters which describe the color.
2019
- 1)and three more parameters which describe the color.
1997
2020
These three parameters default to being interpreted as RGB
1998
(Red, Green, Blue) values. If the boolean capability <STRONG>hls</STRONG>
2021
(Red, Green, Blue) values. If the boolean capability <STRONG>hls</STRONG>
1999
2022
is present, they are instead as HLS (Hue, Lightness, Satu-
2000
2023
ration) indices. The ranges are terminal-dependent.
2001
2024
2002
On an HP-like terminal, <STRONG>initp</STRONG> may give a capability for
2003
changing a color-pair value. It will take seven parame-
2004
ters; a color-pair number (0 to <STRONG>max_pairs</STRONG> - 1), and two
2005
triples describing first background and then foreground
2006
colors. These parameters must be (Red, Green, Blue) or
2025
On an HP-like terminal, <STRONG>initp</STRONG> may give a capability for
2026
changing a color-pair value. It will take seven parame-
2027
ters; a color-pair number (0 to <STRONG>max_pairs</STRONG> - 1), and two
2028
triples describing first background and then foreground
2029
colors. These parameters must be (Red, Green, Blue) or
2007
2030
(Hue, Lightness, Saturation) depending on <STRONG>hls</STRONG>.
2008
2031
2009
On some color terminals, colors collide with highlights.
2032
On some color terminals, colors collide with highlights.
2010
2033
You can register these collisions with the <STRONG>ncv</STRONG> capability.
2011
This is a bit-mask of attributes not to be used when col-
2012
ors are enabled. The correspondence with the attributes
2034
This is a bit-mask of attributes not to be used when col-
2035
ors are enabled. The correspondence with the attributes
2013
2036
understood by <STRONG>curses</STRONG> is as follows:
2014
2037
2015
2038
2022
2045
A_BOLD 5 32
2023
2046
A_INVIS 6 64
2024
2047
A_PROTECT 7 128
2048
2025
2049
A_ALTCHARSET 8 256
2026
2050
2027
For example, on many IBM PC consoles, the underline
2028
attribute collides with the foreground color blue and is
2029
not available in color mode. These should have an <STRONG>ncv</STRONG>
2051
For example, on many IBM PC consoles, the underline
2052
attribute collides with the foreground color blue and is
2053
not available in color mode. These should have an <STRONG>ncv</STRONG>
2030
2054
capability of 2.
2031
2055
2032
SVr4 curses does nothing with <STRONG>ncv</STRONG>, ncurses recognizes it
2056
SVr4 curses does nothing with <STRONG>ncv</STRONG>, ncurses recognizes it
2033
2057
and optimizes the output in favor of colors.
2034
2058
2035
2059
2036
2060
<STRONG>Miscellaneous</STRONG>
2037
If the terminal requires other than a null (zero) charac-
2038
ter as a pad, then this can be given as pad. Only the
2039
first character of the pad string is used. If the termi-
2061
If the terminal requires other than a null (zero) charac-
2062
ter as a pad, then this can be given as pad. Only the
2063
first character of the pad string is used. If the termi-
2040
2064
nal does not have a pad character, specify npc. Note that
2041
ncurses implements the termcap-compatible <STRONG>PC</STRONG> variable;
2042
though the application may set this value to something
2043
other than a null, ncurses will test <STRONG>npc</STRONG> first and use
2065
ncurses implements the termcap-compatible <STRONG>PC</STRONG> variable;
2066
though the application may set this value to something
2067
other than a null, ncurses will test <STRONG>npc</STRONG> first and use
2044
2068
napms if the terminal has no pad character.
2045
2069
2046
If the terminal can move up or down half a line, this can
2047
be indicated with <STRONG>hu</STRONG> (half-line up) and <STRONG>hd</STRONG> (half-line
2070
If the terminal can move up or down half a line, this can
2071
be indicated with <STRONG>hu</STRONG> (half-line up) and <STRONG>hd</STRONG> (half-line
2048
2072
down). This is primarily useful for superscripts and sub-
2049
scripts on hard-copy terminals. If a hard-copy terminal
2050
can eject to the next page (form feed), give this as <STRONG>ff</STRONG>
2073
scripts on hard-copy terminals. If a hard-copy terminal
2074
can eject to the next page (form feed), give this as <STRONG>ff</STRONG>
2051
2075
(usually control L).
2052
2076
2053
If there is a command to repeat a given character a given
2054
number of times (to save time transmitting a large number
2055
of identical characters) this can be indicated with the
2056
parameterized string <STRONG>rep</STRONG>. The first parameter is the
2057
character to be repeated and the second is the number of
2058
times to repeat it. Thus, tparm(repeat_char, 'x', 10) is
2077
If there is a command to repeat a given character a given
2078
number of times (to save time transmitting a large number
2079
of identical characters) this can be indicated with the
2080
parameterized string <STRONG>rep</STRONG>. The first parameter is the
2081
character to be repeated and the second is the number of
2082
times to repeat it. Thus, tparm(repeat_char, 'x', 10) is
2059
2083
the same as `xxxxxxxxxx'.
2060
2084
2061
If the terminal has a settable command character, such as
2062
the TEKTRONIX 4025, this can be indicated with <STRONG>cmdch</STRONG>. A
2085
If the terminal has a settable command character, such as
2086
the TEKTRONIX 4025, this can be indicated with <STRONG>cmdch</STRONG>. A
2063
2087
prototype command character is chosen which is used in all
2064
capabilities. This character is given in the <STRONG>cmdch</STRONG> capa-
2065
bility to identify it. The following convention is sup-
2066
ported on some UNIX systems: The environment is to be
2067
searched for a <STRONG>CC</STRONG> variable, and if found, all occurrences
2088
capabilities. This character is given in the <STRONG>cmdch</STRONG> capa-
2089
bility to identify it. The following convention is sup-
2090
ported on some UNIX systems: The environment is to be
2091
searched for a <STRONG>CC</STRONG> variable, and if found, all occurrences
2068
2092
of the prototype character are replaced with the character
2069
2093
in the environment variable.
2070
2094
2071
Terminal descriptions that do not represent a specific
2095
Terminal descriptions that do not represent a specific
2072
2096
kind of known terminal, such as <EM>switch</EM>, <EM>dialup</EM>, <EM>patch</EM>, and
2073
<EM>network</EM>, should include the <STRONG>gn</STRONG> (generic) capability so
2074
that programs can complain that they do not know how to
2075
talk to the terminal. (This capability does not apply to
2076
<EM>virtual</EM> terminal descriptions for which the escape
2097
<EM>network</EM>, should include the <STRONG>gn</STRONG> (generic) capability so
2098
that programs can complain that they do not know how to
2099
talk to the terminal. (This capability does not apply to
2100
<EM>virtual</EM> terminal descriptions for which the escape
2077
2101
sequences are known.)
2078
2102
2079
If the terminal has a ``meta key'' which acts as a shift
2080
key, setting the 8th bit of any character transmitted,
2081
this fact can be indicated with <STRONG>km</STRONG>. Otherwise, software
2103
If the terminal has a ``meta key'' which acts as a shift
2104
key, setting the 8th bit of any character transmitted,
2105
this fact can be indicated with <STRONG>km</STRONG>. Otherwise, software
2082
2106
will assume that the 8th bit is parity and it will usually
2083
be cleared. If strings exist to turn this ``meta mode''
2107
be cleared. If strings exist to turn this ``meta mode''
2084
2108
on and off, they can be given as <STRONG>smm</STRONG> and <STRONG>rmm</STRONG>.
2085
2109
2086
If the terminal has more lines of memory than will fit on
2087
the screen at once, the number of lines of memory can be
2088
indicated with <STRONG>lm</STRONG>. A value of <STRONG>lm</STRONG>#0 indicates that the
2110
If the terminal has more lines of memory than will fit on
2111
the screen at once, the number of lines of memory can be
2112
indicated with <STRONG>lm</STRONG>. A value of <STRONG>lm</STRONG>#0 indicates that the
2089
2113
number of lines is not fixed, but that there is still more
2090
2114
memory than fits on the screen.
2091
2115
2092
2116
If the terminal is one of those supported by the UNIX vir-
2093
tual terminal protocol, the terminal number can be given
2117
tual terminal protocol, the terminal number can be given
2094
2118
as <STRONG>vt</STRONG>.
2095
2119
2096
2120
Media copy strings which control an auxiliary printer con-
2097
2121
nected to the terminal can be given as <STRONG>mc0</STRONG>: print the con-
2098
tents of the screen, <STRONG>mc4</STRONG>: turn off the printer, and <STRONG>mc5</STRONG>:
2099
turn on the printer. When the printer is on, all text
2100
sent to the terminal will be sent to the printer. It is
2122
tents of the screen, <STRONG>mc4</STRONG>: turn off the printer, and <STRONG>mc5</STRONG>:
2123
turn on the printer. When the printer is on, all text
2124
sent to the terminal will be sent to the printer. It is
2101
2125
undefined whether the text is also displayed on the termi-
2102
2126
nal screen when the printer is on. A variation <STRONG>mc5p</STRONG> takes
2103
2127
one parameter, and leaves the printer on for as many char-
2104
acters as the value of the parameter, then turns the
2105
printer off. The parameter should not exceed 255. All
2128
acters as the value of the parameter, then turns the
2129
printer off. The parameter should not exceed 255. All
2106
2130
text, including <STRONG>mc4</STRONG>, is transparently passed to the
2107
2131
printer while an <STRONG>mc5p</STRONG> is in effect.
2108
2132
2109
2133
2110
2134
<STRONG>Glitches</STRONG> <STRONG>and</STRONG> <STRONG>Braindamage</STRONG>
2111
Hazeltine terminals, which do not allow `~' characters to
2135
Hazeltine terminals, which do not allow `~' characters to
2112
2136
be displayed should indicate <STRONG>hz</STRONG>.
2113
2137
2114
2138
Terminals which ignore a line-feed immediately after an <STRONG>am</STRONG>
2115
2139
wrap, such as the Concept and vt100, should indicate <STRONG>xenl</STRONG>.
2116
2140
2117
If <STRONG>el</STRONG> is required to get rid of standout (instead of
2118
merely writing normal text on top of it), <STRONG>xhp</STRONG> should be
2141
If <STRONG>el</STRONG> is required to get rid of standout (instead of
2142
merely writing normal text on top of it), <STRONG>xhp</STRONG> should be
2119
2143
given.
2120
2144
2121
Teleray terminals, where tabs turn all characters moved
2122
over to blanks, should indicate <STRONG>xt</STRONG> (destructive tabs).
2123
Note: the variable indicating this is now
2124
`dest_tabs_magic_smso'; in older versions, it was tel-
2145
Teleray terminals, where tabs turn all characters moved
2146
over to blanks, should indicate <STRONG>xt</STRONG> (destructive tabs).
2147
Note: the variable indicating this is now
2148
`dest_tabs_magic_smso'; in older versions, it was tel-
2125
2149
eray_glitch. This glitch is also taken to mean that it is
2126
not possible to position the cursor on top of a ``magic
2150
not possible to position the cursor on top of a ``magic
2127
2151
cookie'', that to erase standout mode it is instead neces-
2128
2152
sary to use delete and insert line. The ncurses implemen-
2129
2153
tation ignores this glitch.
2130
2154
2131
The Beehive Superbee, which is unable to correctly trans-
2132
mit the escape or control C characters, has <STRONG>xsb</STRONG>, indicat-
2133
ing that the f1 key is used for escape and f2 for control
2134
C. (Only certain Superbees have this problem, depending
2135
on the ROM.) Note that in older terminfo versions, this
2136
capability was called `beehive_glitch'; it is now
2155
The Beehive Superbee, which is unable to correctly trans-
2156
mit the escape or control C characters, has <STRONG>xsb</STRONG>, indicat-
2157
ing that the f1 key is used for escape and f2 for control
2158
C. (Only certain Superbees have this problem, depending
2159
on the ROM.) Note that in older terminfo versions, this
2160
capability was called `beehive_glitch'; it is now
2137
2161
`no_esc_ctl_c'.
2138
2162
2139
Other specific terminal problems may be corrected by
2163
Other specific terminal problems may be corrected by
2140
2164
adding more capabilities of the form <STRONG>x</STRONG><EM>x</EM>.
2141
2165
2142
2166
2143
2167
<STRONG>Similar</STRONG> <STRONG>Terminals</STRONG>
2144
2168
If there are two very similar terminals, one (the variant)
2145
can be defined as being just like the other (the base)
2146
with certain exceptions. In the definition of the vari-
2147
ant, the string capability <STRONG>use</STRONG> can be given with the name
2148
of the base terminal. The capabilities given before <STRONG>use</STRONG>
2149
override those in the base type named by <STRONG>use</STRONG>. If there
2150
are multiple <STRONG>use</STRONG> capabilities, they are merged in reverse
2151
order. That is, the rightmost <STRONG>use</STRONG> reference is processed
2152
first, then the one to its left, and so forth. Capabili-
2153
ties given explicitly in the entry override those brought
2169
can be defined as being just like the other (the base)
2170
with certain exceptions. In the definition of the vari-
2171
ant, the string capability <STRONG>use</STRONG> can be given with the name
2172
of the base terminal. The capabilities given before <STRONG>use</STRONG>
2173
override those in the base type named by <STRONG>use</STRONG>. If there
2174
are multiple <STRONG>use</STRONG> capabilities, they are merged in reverse
2175
order. That is, the rightmost <STRONG>use</STRONG> reference is processed
2176
first, then the one to its left, and so forth. Capabili-
2177
ties given explicitly in the entry override those brought
2154
2178
in by <STRONG>use</STRONG> references.
2155
2179
2156
2180
A capability can be canceled by placing <STRONG>xx@</STRONG> to the left of
2157
the use reference that imports it, where <EM>xx</EM> is the capa-
2181
the use reference that imports it, where <EM>xx</EM> is the capa-
2158
2182
bility. For example, the entry
2159
2183
2160
2184
2621-nl, smkx@, rmkx@, use=2621,
2161
2185
2162
defines a 2621-nl that does not have the <STRONG>smkx</STRONG> or <STRONG>rmkx</STRONG>
2163
capabilities, and hence does not turn on the function key
2164
labels when in visual mode. This is useful for different
2186
defines a 2621-nl that does not have the <STRONG>smkx</STRONG> or <STRONG>rmkx</STRONG>
2187
capabilities, and hence does not turn on the function key
2188
labels when in visual mode. This is useful for different
2165
2189
modes for a terminal, or for different user preferences.
2166
2190
2167
2191
2168
2192
<STRONG>Pitfalls</STRONG> <STRONG>of</STRONG> <STRONG>Long</STRONG> <STRONG>Entries</STRONG>
2169
Long terminfo entries are unlikely to be a problem; to
2170
date, no entry has even approached terminfo's 4096-byte
2193
Long terminfo entries are unlikely to be a problem; to
2194
date, no entry has even approached terminfo's 4096-byte
2171
2195
string-table maximum. Unfortunately, the termcap transla-
2172
2196
tions are much more strictly limited (to 1023 bytes), thus
2173
termcap translations of long terminfo entries can cause
2197
termcap translations of long terminfo entries can cause
2174
2198
problems.
2175
2199
2176
The man pages for 4.3BSD and older versions of <STRONG>tgetent()</STRONG>
2177
instruct the user to allocate a 1024-byte buffer for the
2178
termcap entry. The entry gets null-terminated by the
2200
The man pages for 4.3BSD and older versions of <STRONG>tgetent()</STRONG>
2201
instruct the user to allocate a 1024-byte buffer for the
2202
termcap entry. The entry gets null-terminated by the
2179
2203
termcap library, so that makes the maximum safe length for
2180
a termcap entry 1k-1 (1023) bytes. Depending on what the
2181
application and the termcap library being used does, and
2204
a termcap entry 1k-1 (1023) bytes. Depending on what the
2205
application and the termcap library being used does, and
2182
2206
where in the termcap file the terminal type that <STRONG>tgetent()</STRONG>
2183
2207
is searching for is, several bad things can happen.
2184
2208
2185
Some termcap libraries print a warning message or exit if
2186
they find an entry that's longer than 1023 bytes; others
2187
do not; others truncate the entries to 1023 bytes. Some
2209
Some termcap libraries print a warning message or exit if
2210
they find an entry that's longer than 1023 bytes; others
2211
do not; others truncate the entries to 1023 bytes. Some
2188
2212
application programs allocate more than the recommended 1K
2189
2213
for the termcap entry; others do not.
2190
2214
2191
2215
Each termcap entry has two important sizes associated with
2192
2216
it: before "tc" expansion, and after "tc" expansion. "tc"
2193
is the capability that tacks on another termcap entry to
2194
the end of the current one, to add on its capabilities.
2195
If a termcap entry does not use the "tc" capability, then
2217
is the capability that tacks on another termcap entry to
2218
the end of the current one, to add on its capabilities.
2219
If a termcap entry does not use the "tc" capability, then
2196
2220
of course the two lengths are the same.
2197
2221
2198
The "before tc expansion" length is the most important
2199
one, because it affects more than just users of that par-
2200
ticular terminal. This is the length of the entry as it
2222
The "before tc expansion" length is the most important
2223
one, because it affects more than just users of that par-
2224
ticular terminal. This is the length of the entry as it
2201
2225
exists in /etc/termcap, minus the backslash-newline pairs,
2202
2226
which <STRONG>tgetent()</STRONG> strips out while reading it. Some termcap
2203
libraries strip off the final newline, too (GNU termcap
2227
libraries strip off the final newline, too (GNU termcap
2204
2228
does not). Now suppose:
2205
2229
2206
* a termcap entry before expansion is more than 1023
2230
* a termcap entry before expansion is more than 1023
2207
2231
bytes long,
2208
2232
2209
2233
* and the application has only allocated a 1k buffer,
2210
2234
2211
* and the termcap library (like the one in BSD/OS 1.1
2212
and GNU) reads the whole entry into the buffer, no
2213
matter what its length, to see if it's the entry it
2235
* and the termcap library (like the one in BSD/OS 1.1
2236
and GNU) reads the whole entry into the buffer, no
2237
matter what its length, to see if it's the entry it
2214
2238
wants,
2215
2239
2216
* and <STRONG>tgetent()</STRONG> is searching for a terminal type that
2240
* and <STRONG>tgetent()</STRONG> is searching for a terminal type that
2217
2241
either is the long entry, appears in the termcap file
2218
after the long entry, or does not appear in the file
2219
at all (so that <STRONG>tgetent()</STRONG> has to search the whole
2242
after the long entry, or does not appear in the file
2243
at all (so that <STRONG>tgetent()</STRONG> has to search the whole
2220
2244
termcap file).
2221
2245
2222
Then <STRONG>tgetent()</STRONG> will overwrite memory, perhaps its stack,
2223
and probably core dump the program. Programs like telnet
2224
are particularly vulnerable; modern telnets pass along
2225
values like the terminal type automatically. The results
2226
are almost as undesirable with a termcap library, like
2227
SunOS 4.1.3 and Ultrix 4.4, that prints warning messages
2228
when it reads an overly long termcap entry. If a termcap
2229
library truncates long entries, like OSF/1 3.0, it is
2230
immune to dying here but will return incorrect data for
2246
Then <STRONG>tgetent()</STRONG> will overwrite memory, perhaps its stack,
2247
and probably core dump the program. Programs like telnet
2248
are particularly vulnerable; modern telnets pass along
2249
values like the terminal type automatically. The results
2250
are almost as undesirable with a termcap library, like
2251
SunOS 4.1.3 and Ultrix 4.4, that prints warning messages
2252
when it reads an overly long termcap entry. If a termcap
2253
library truncates long entries, like OSF/1 3.0, it is
2254
immune to dying here but will return incorrect data for
2231
2255
the terminal.
2232
2256
2233
2257
The "after tc expansion" length will have a similar effect
2234
2258
to the above, but only for people who actually set TERM to
2235
that terminal type, since <STRONG>tgetent()</STRONG> only does "tc" expan-
2259
that terminal type, since <STRONG>tgetent()</STRONG> only does "tc" expan-
2236
2260
sion once it's found the terminal type it was looking for,
2237
2261
not while searching.
2238
2262
2239
2263
In summary, a termcap entry that is longer than 1023 bytes
2240
can cause, on various combinations of termcap libraries
2241
and applications, a core dump, warnings, or incorrect
2242
operation. If it's too long even before "tc" expansion,
2264
can cause, on various combinations of termcap libraries
2265
and applications, a core dump, warnings, or incorrect
2266
operation. If it's too long even before "tc" expansion,
2243
2267
it will have this effect even for users of some other ter-
2244
minal types and users whose TERM variable does not have a
2268
minal types and users whose TERM variable does not have a
2245
2269
termcap entry.
2246
2270
2247
2271
When in -C (translate to termcap) mode, the <STRONG>ncurses</STRONG> imple-
2248
mentation of <STRONG><A HREF="tic.1.html">tic(1)</A></STRONG> issues warning messages when the pre-
2249
tc length of a termcap translation is too long. The -c
2250
(check) option also checks resolved (after tc expansion)
2272
mentation of <STRONG><A HREF="tic.1.html">tic(1)</A></STRONG> issues warning messages when the pre-
2273
tc length of a termcap translation is too long. The -c
2274
(check) option also checks resolved (after tc expansion)
2251
2275
lengths.
2252
2276
2253
2277
<STRONG>Binary</STRONG> <STRONG>Compatibility</STRONG>
2254
It is not wise to count on portability of binary terminfo
2255
entries between commercial UNIX versions. The problem is
2256
that there are at least two versions of terminfo (under
2278
It is not wise to count on portability of binary terminfo
2279
entries between commercial UNIX versions. The problem is
2280
that there are at least two versions of terminfo (under
2257
2281
HP-UX and AIX) which diverged from System V terminfo after
2258
SVr1, and have added extension capabilities to the string
2259
table that (in the binary format) collide with System V
2282
SVr1, and have added extension capabilities to the string
2283
table that (in the binary format) collide with System V
2260
2284
and XSI Curses extensions.
2261
2285
2262
2286
2263
2287
</PRE>
2264
2288
<H2>EXTENSIONS</H2><PRE>
2265
Some SVr4 <STRONG>curses</STRONG> implementations, and all previous to
2266
SVr4, do not interpret the %A and %O operators in parame-
2289
Some SVr4 <STRONG>curses</STRONG> implementations, and all previous to
2290
SVr4, do not interpret the %A and %O operators in parame-
2267
2291
ter strings.
2268
2292
2269
SVr4/XPG4 do not specify whether <STRONG>msgr</STRONG> licenses movement
2270
while in an alternate-character-set mode (such modes may,
2271
among other things, map CR and NL to characters that do
2272
not trigger local motions). The <STRONG>ncurses</STRONG> implementation
2273
ignores <STRONG>msgr</STRONG> in <STRONG>ALTCHARSET</STRONG> mode. This raises the possi-
2274
bility that an XPG4 implementation making the opposite
2275
interpretation may need terminfo entries made for <STRONG>ncurses</STRONG>
2293
SVr4/XPG4 do not specify whether <STRONG>msgr</STRONG> licenses movement
2294
while in an alternate-character-set mode (such modes may,
2295
among other things, map CR and NL to characters that do
2296
not trigger local motions). The <STRONG>ncurses</STRONG> implementation
2297
ignores <STRONG>msgr</STRONG> in <STRONG>ALTCHARSET</STRONG> mode. This raises the possi-
2298
bility that an XPG4 implementation making the opposite
2299
interpretation may need terminfo entries made for <STRONG>ncurses</STRONG>
2276
2300
to have <STRONG>msgr</STRONG> turned off.
2277
2301
2278
The <STRONG>ncurses</STRONG> library handles insert-character and insert-
2302
The <STRONG>ncurses</STRONG> library handles insert-character and insert-
2279
2303
character modes in a slightly non-standard way to get bet-
2280
ter update efficiency. See the <STRONG>Insert/Delete</STRONG> <STRONG>Character</STRONG>
2304
ter update efficiency. See the <STRONG>Insert/Delete</STRONG> <STRONG>Character</STRONG>
2281
2305
subsection above.
2282
2306
2283
The parameter substitutions for <STRONG>set_clock</STRONG> and <STRONG>dis-</STRONG>
2284
<STRONG>play_clock</STRONG> are not documented in SVr4 or the XSI Curses
2307
The parameter substitutions for <STRONG>set_clock</STRONG> and <STRONG>dis-</STRONG>
2308
<STRONG>play_clock</STRONG> are not documented in SVr4 or the XSI Curses
2285
2309
standard. They are deduced from the documentation for the
2286
2310
AT&T 505 terminal.
2287
2311
2288
Be careful assigning the <STRONG>kmous</STRONG> capability. The <STRONG>ncurses</STRONG>
2289
wants to interpret it as <STRONG>KEY_MOUSE</STRONG>, for use by terminals
2290
and emulators like xterm that can return mouse-tracking
2312
Be careful assigning the <STRONG>kmous</STRONG> capability. The <STRONG>ncurses</STRONG>
2313
wants to interpret it as <STRONG>KEY_MOUSE</STRONG>, for use by terminals
2314
and emulators like xterm that can return mouse-tracking
2291
2315
information in the keyboard-input stream.
2292
2316
2293
Different commercial ports of terminfo and curses support
2294
different subsets of the XSI Curses standard and (in some
2317
Different commercial ports of terminfo and curses support
2318
different subsets of the XSI Curses standard and (in some
2295
2319
cases) different extension sets. Here is a summary, accu-
2296
2320
rate as of October 1995:
2297
2321
2298
2322
<STRONG>SVR4,</STRONG> <STRONG>Solaris,</STRONG> <STRONG>ncurses</STRONG> -- These support all SVr4 capabili-
2299
2323
ties.
2300
2324
2301
<STRONG>SGI</STRONG> -- Supports the SVr4 set, adds one undocumented
2325
<STRONG>SGI</STRONG> -- Supports the SVr4 set, adds one undocumented
2302
2326
extended string capability (<STRONG>set_pglen</STRONG>).
2303
2327
2304
<STRONG>SVr1,</STRONG> <STRONG>Ultrix</STRONG> -- These support a restricted subset of ter-
2305
minfo capabilities. The booleans end with <STRONG>xon_xoff</STRONG>; the
2306
numerics with <STRONG>width_status_line</STRONG>; and the strings with
2328
<STRONG>SVr1,</STRONG> <STRONG>Ultrix</STRONG> -- These support a restricted subset of ter-
2329
minfo capabilities. The booleans end with <STRONG>xon_xoff</STRONG>; the
2330
numerics with <STRONG>width_status_line</STRONG>; and the strings with
2307
2331
<STRONG>prtr_non</STRONG>.
2308
2332
2309
<STRONG>HP/UX</STRONG> -- Supports the SVr1 subset, plus the SVr[234]
2333
<STRONG>HP/UX</STRONG> -- Supports the SVr1 subset, plus the SVr[234]
2310
2334
numerics <STRONG>num_labels</STRONG>, <STRONG>label_height</STRONG>, <STRONG>label_width</STRONG>, plus func-
2311
tion keys 11 through 63, plus <STRONG>plab_norm</STRONG>, <STRONG>label_on</STRONG>, and
2335
tion keys 11 through 63, plus <STRONG>plab_norm</STRONG>, <STRONG>label_on</STRONG>, and
2312
2336
<STRONG>label_off</STRONG>, plus some incompatible extensions in the string
2313
2337
table.
2314
2338
2315
<STRONG>AIX</STRONG> -- Supports the SVr1 subset, plus function keys 11
2316
through 63, plus a number of incompatible string table
2339
<STRONG>AIX</STRONG> -- Supports the SVr1 subset, plus function keys 11
2340
through 63, plus a number of incompatible string table
2317
2341
extensions.
2318
2342
2319
<STRONG>OSF</STRONG> -- Supports both the SVr4 set and the AIX extensions.
2343
<STRONG>OSF</STRONG> -- Supports both the SVr4 set and the AIX extensions.
2320
2344
2321
2345
2322
2346
</PRE>
2332
2356
2333
2357
</PRE>
2334
2358
<H2>AUTHORS</H2><PRE>
2335
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
2359
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
2336
2360
Based on pcurses by Pavel Curtis.
2337
2361
2338
2362
Loggerhead is a web-based interface for Breezy
Version: 2.0.1