Commit | Line | Data |
---|---|---|
110d9509 KB |
1 | .\" Copyright (c) 1985 The Regents of the University of California. |
2 | .\" All rights reserved. | |
c4737001 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
110d9509 | 5 | .\" |
91cff1e1 | 6 | .\" @(#)termcap.5 6.8 (Berkeley) %G% |
c4737001 | 7 | .\" |
ef978bfe JB |
8 | .ie n \{\ |
9 | . ds lq \&"\" | |
10 | . ds rq \&"\" | |
11 | .\} | |
12 | .el \{\ | |
13 | . ds rq '' | |
14 | . ds lq `` | |
15 | .\} | |
c4737001 | 16 | .tr || |
ef978bfe JB |
17 | .tr *\(** |
18 | .hw trans-parently | |
110d9509 | 19 | .TH TERMCAP 5 "" |
ef978bfe | 20 | .UC |
c4737001 KM |
21 | .SH NAME |
22 | termcap \- terminal capability data base | |
23 | .SH SYNOPSIS | |
24 | /etc/termcap | |
25 | .SH DESCRIPTION | |
ef978bfe | 26 | .I Termcap\^ |
c4737001 KM |
27 | is a data base describing terminals, |
28 | used, | |
29 | .IR e.g. , | |
30 | by | |
ef978bfe | 31 | .IR vi\^ (1) |
c4737001 | 32 | and |
ef978bfe | 33 | .IR curses\^ (3X). |
c4737001 | 34 | Terminals are described in |
ef978bfe JB |
35 | .I termcap\^ |
36 | by giving a set of capabilities that they have and by describing | |
c4737001 KM |
37 | how operations are performed. |
38 | Padding requirements and initialization sequences | |
39 | are included in | |
ef978bfe | 40 | .IR termcap\^ . |
c4737001 KM |
41 | .PP |
42 | Entries in | |
ef978bfe JB |
43 | .I termcap\^ |
44 | consist of a number of `:'-separated fields. | |
45 | The first entry for each terminal gives the names that are known for the | |
46 | terminal, separated by `|' characters. | |
47 | The first name is always two characters | |
48 | long and is used by older systems which store the terminal type | |
49 | in a 16-bit word in a system-wide data base. | |
50 | The second name given is the most common abbreviation for the terminal, | |
51 | the last name given should be a long name fully identifying the terminal, | |
52 | and all others are understood as synonyms for the terminal name. | |
53 | All names but the first and last | |
54 | should be in lower case and contain no blanks; | |
55 | the last name may well contain | |
56 | upper case and blanks for readability. | |
57 | .PP | |
58 | Terminal names (except for the last, verbose entry) | |
59 | should be chosen using the following conventions. | |
60 | The particular piece of hardware making up the terminal | |
61 | should have a root name chosen, thus \*(lqhp2621\*(rq. | |
62 | This name should not contain hyphens. | |
63 | Modes that the hardware can be in | |
64 | or user preferences | |
65 | should be indicated by appending a hyphen and an indicator of the mode. | |
66 | Therefore, a \*(lqvt100\*(rq in 132-column mode would be \*(lqvt100-w\*(rq. | |
67 | The following suffixes should be used where possible: | |
68 | .sp | |
69 | .ev | |
70 | .ta | |
71 | .ta \w'\fBSuffix\fP\ \ \ 'u +\w'With automatic margins (usually default)\ \ 'u | |
72 | .nf | |
73 | .if t \{\ | |
74 | .nr Xx \n(.lu-\n(.i-\w'\fBSuffix\fP\ \ \ With automatic margins (usually default)\ \ vt100-am'u | |
75 | .in +\n(Xxu/2u | |
76 | .\} | |
77 | \fBSuffix Meaning Example\fP | |
78 | -w Wide mode (more than 80 columns) vt100-w | |
79 | -am With automatic margins (usually default) vt100-am | |
80 | -nam Without automatic margins vt100-nam | |
81 | -\fIn\fP Number of lines on the screen aaa-60 | |
82 | -na No arrow keys (leave them in local) concept100-na | |
83 | -\fIn\^\fPp Number of pages of memory concept100-4p | |
84 | -rv Reverse video concept100-rv | |
85 | .fi | |
86 | .ev | |
c4737001 | 87 | .SH CAPABILITIES |
ef978bfe JB |
88 | .PP |
89 | The characters in the | |
90 | .I Notes | |
91 | field in the table have the following meanings | |
92 | (more than one may apply to a capability): | |
93 | .PP | |
94 | .ev | |
95 | .ta | |
96 | .ta \w'N\ \ \ 'u | |
c4737001 | 97 | .nf |
ef978bfe JB |
98 | N indicates numeric parameter(s) |
99 | P indicates that padding may be specified | |
100 | * indicates that padding may be based on the number of lines affected | |
101 | o indicates capability is obsolete | |
102 | .fi | |
103 | .ev | |
104 | .PP | |
105 | \*(lqObsolete\*(rq capabilities have no | |
106 | .I terminfo\^ | |
107 | equivalents, | |
108 | since they were considered useless, | |
109 | or are subsumed by other capabilities. | |
110 | New software should not rely on them at all. | |
111 | .PP | |
112 | .nf | |
113 | .ta \w'\fBName \fP'u +\w'\fBType \fP'u +\w'\fBNotes \fP'u | |
114 | \fBName Type Notes Description\fP | |
c4737001 | 115 | ae str (P) End alternate character set |
ef978bfe | 116 | AL str (NP*) Add \fIn\^\fP new blank lines |
c4737001 KM |
117 | al str (P*) Add new blank line |
118 | am bool Terminal has automatic margins | |
119 | as str (P) Start alternate character set | |
ef978bfe JB |
120 | bc str (o) Backspace if not \fB^H\fP |
121 | bl str (P) Audible signal (bell) | |
122 | bs bool (o) Terminal can backspace with \fB^H\fP | |
c4737001 | 123 | bt str (P) Back tab |
ef978bfe JB |
124 | bw bool \fBle\fP (backspace) wraps from column 0 to last column |
125 | CC str Terminal settable command character in prototype | |
c4737001 KM |
126 | cd str (P*) Clear to end of display |
127 | ce str (P) Clear to end of line | |
ef978bfe JB |
128 | ch str (NP) Set cursor column (horizontal position) |
129 | cl str (P*) Clear screen and home cursor | |
130 | CM str (NP) Memory-relative cursor addressing | |
131 | cm str (NP) Screen-relative cursor motion | |
f3531ae0 | 132 | co num Number of columns in a line (See BUGS section below) |
ef978bfe JB |
133 | cr str (P) Carriage return |
134 | cs str (NP) Change scrolling region (VT100) | |
135 | ct str (P) Clear all tab stops | |
136 | cv str (NP) Set cursor row (vertical position) | |
137 | da bool Display may be retained above the screen | |
138 | dB num (o) Milliseconds of \fBbs\fP delay needed (default 0) | |
139 | db bool Display may be retained below the screen | |
140 | DC str (NP*) Delete \fIn\^\fP characters | |
141 | dC num (o) Milliseconds of \fBcr\fP delay needed (default 0) | |
c4737001 | 142 | dc str (P*) Delete character |
ef978bfe JB |
143 | dF num (o) Milliseconds of \fBff\fP delay needed (default 0) |
144 | DL str (NP*) Delete \fIn\^\fP lines | |
c4737001 | 145 | dl str (P*) Delete line |
ef978bfe JB |
146 | dm str Enter delete mode |
147 | dN num (o) Milliseconds of \fBnl\fP delay needed (default 0) | |
148 | DO str (NP*) Move cursor down \fIn\^\fP lines | |
c4737001 | 149 | do str Down one line |
ef978bfe JB |
150 | ds str Disable status line |
151 | dT num (o) Milliseconds of horizontal tab delay needed (default 0) | |
152 | dV num (o) Milliseconds of vertical tab delay needed (default 0) | |
153 | ec str (NP) Erase \fIn\^\fP characters | |
c4737001 | 154 | ed str End delete mode |
ef978bfe JB |
155 | ei str End insert mode |
156 | eo bool Can erase overstrikes with a blank | |
157 | EP bool (o) Even parity | |
158 | es bool Escape can be used on the status line | |
159 | ff str (P*) Hardcopy terminal page eject | |
160 | fs str Return from status line | |
161 | gn bool Generic line type (\fIe.g.\fP dialup, switch) | |
c4737001 | 162 | hc bool Hardcopy terminal |
ef978bfe | 163 | HD bool (o) Half-duplex |
c4737001 | 164 | hd str Half-line down (forward 1/2 linefeed) |
ef978bfe JB |
165 | ho str (P) Home cursor |
166 | hs bool Has extra \*(lqstatus line\*(rq | |
c4737001 | 167 | hu str Half-line up (reverse 1/2 linefeed) |
ef978bfe JB |
168 | hz bool Cannot print ~s (Hazeltine) |
169 | i1-i3 str Terminal initialization strings (\fIterminfo\^\fP only) | |
170 | IC str (NP*) Insert \fIn\^\fP blank characters | |
171 | ic str (P*) Insert character | |
172 | if str Name of file containing initialization string | |
173 | im str Enter insert mode | |
174 | in bool Insert mode distinguishes nulls | |
175 | iP str Pathname of program for initialization (\fIterminfo\^\fP only) | |
c4737001 | 176 | ip str (P*) Insert pad after character inserted |
ef978bfe JB |
177 | is str Terminal initialization string (\fItermcap\^\fP only) |
178 | it num Tabs initially every \fIn\^\fP positions | |
179 | K1 str Sent by keypad upper left | |
180 | K2 str Sent by keypad upper right | |
181 | K3 str Sent by keypad center | |
182 | K4 str Sent by keypad lower left | |
183 | K5 str Sent by keypad lower right | |
184 | k0-k9 str Sent by function keys 0-9 | |
185 | kA str Sent by insert-line key | |
186 | ka str Sent by clear-all-tabs key | |
c4737001 | 187 | kb str Sent by backspace key |
ef978bfe JB |
188 | kC str Sent by clear-screen or erase key |
189 | kD str Sent by delete-character key | |
190 | kd str Sent by down-arrow key | |
191 | kE str Sent by clear-to-end-of-line key | |
c4737001 | 192 | ke str Out of \*(lqkeypad transmit\*(rq mode |
ef978bfe JB |
193 | kF str Sent by scroll-forward/down key |
194 | kH str Sent by home-down key | |
c4737001 | 195 | kh str Sent by home key |
ef978bfe JB |
196 | kI str Sent by insert-character or enter-insert-mode key |
197 | kL str Sent by delete-line key | |
198 | kl str Sent by left-arrow key | |
199 | kM str Sent by insert key while in insert mode | |
200 | km bool Has a \*(lqmeta\*(rq key (shift, sets parity bit) | |
201 | kN str Sent by next-page key | |
202 | kn num (o) Number of function (\fBk0\fP\-\fBk9\fP) keys (default 0) | |
203 | ko str (o) Termcap entries for other non-function keys | |
204 | kP str Sent by previous-page key | |
205 | kR str Sent by scroll-backward/up key | |
206 | kr str Sent by right-arrow key | |
207 | kS str Sent by clear-to-end-of-screen key | |
c4737001 | 208 | ks str Put terminal in \*(lqkeypad transmit\*(rq mode |
ef978bfe JB |
209 | kT str Sent by set-tab key |
210 | kt str Sent by clear-tab key | |
211 | ku str Sent by up-arrow key | |
212 | l0-l9 str Labels on function keys if not \*(lqf\fIn\^\fP\*(rq | |
213 | LC bool (o) Lower-case only | |
214 | LE str (NP) Move cursor left \fIn\^\fP positions | |
215 | le str (P) Move cursor left one position | |
f3531ae0 | 216 | li num Number of lines on screen or page (See BUGS section below) |
c007a4d8 | 217 | ll str Last line, first column |
ef978bfe JB |
218 | lm num Lines of memory if > \fBli\fP (0 means varies) |
219 | ma str (o) Arrow key map (used by \fIvi\^\fP version 2 only) | |
220 | mb str Turn on blinking attribute | |
221 | md str Turn on bold (extra bright) attribute | |
222 | me str Turn off all attributes | |
223 | mh str Turn on half-bright attribute | |
c4737001 | 224 | mi bool Safe to move while in insert mode |
ef978bfe JB |
225 | mk str Turn on blank attribute (characters invisible) |
226 | ml str (o) Memory lock on above cursor | |
227 | mm str Turn on \*(lqmeta mode\*(rq (8th bit) | |
228 | mo str Turn off \*(lqmeta mode\*(rq | |
229 | mp str Turn on protected attribute | |
230 | mr str Turn on reverse-video attibute | |
231 | ms bool Safe to move in standout modes | |
232 | mu str (o) Memory unlock (turn off memory lock) | |
233 | nc bool (o) No correctly-working \fBcr\fP (Datamedia 2500, Hazeltine 2000) | |
c4737001 | 234 | nd str Non-destructive space (cursor right) |
ef978bfe JB |
235 | NL bool (o) \fB\\n\fP is newline, not line feed |
236 | nl str (o) Newline character if not \fB\\n\fP | |
237 | ns bool (o) Terminal is a \s-1CRT\s0 but doesn't scroll | |
238 | nw str (P) Newline (behaves like \fBcr\fP followed by \fBdo\fP) | |
239 | OP bool (o) Odd parity | |
c4737001 | 240 | os bool Terminal overstrikes |
ef978bfe JB |
241 | pb num Lowest baud where delays are required |
242 | pc str Pad character (default \s-2NUL\s0) | |
243 | pf str Turn off the printer | |
244 | pk str Program function key \fIn\^\fP to type string \fIs\fP (\fIterminfo\^\fP only) | |
245 | pl str Program function key \fIn\^\fP to execute string \fIs\fP (\fIterminfo\^\fP only) | |
246 | pO str (N) Turn on the printer for \fIn\^\fP bytes | |
247 | po str Turn on the printer | |
248 | ps str Print contents of the screen | |
249 | pt bool (o) Has hardware tabs (may need to be set with \fBis\fP) | |
250 | px str Program function key \fIn\^\fP to transmit string \fIs\fP (\fIterminfo\^\fP only) | |
251 | r1-r3 str Reset terminal completely to sane modes (\fIterminfo\^\fP only) | |
252 | rc str (P) Restore cursor to position of last \fBsc\fP | |
253 | rf str Name of file containing reset codes | |
254 | RI str (NP) Move cursor right \fIn\^\fP positions | |
255 | rp str (NP*) Repeat character \fIc n\^\fP times | |
256 | rs str Reset terminal completely to sane modes (\fItermcap\^\fP only) | |
257 | sa str (NP) Define the video attributes | |
258 | sc str (P) Save cursor position | |
259 | se str End standout mode | |
260 | SF str (NP*) Scroll forward \fIn\^\fP lines | |
261 | sf str (P) Scroll text up | |
262 | sg num Number of garbage chars left by \fBso\fP or \fBse\fP (default 0) | |
263 | so str Begin standout mode | |
264 | SR str (NP*) Scroll backward \fIn\^\fP lines | |
265 | sr str (P) Scroll text down | |
266 | st str Set a tab in all rows, current column | |
267 | ta str (P) Tab to next 8-position hardware tab stop | |
268 | tc str Entry of similar terminal \- must be last | |
269 | te str String to end programs that use \fItermcap\fP | |
270 | ti str String to begin programs that use \fItermcap\fP | |
271 | ts str (N) Go to status line, column \fIn\^\fP | |
272 | UC bool (o) Upper-case only | |
273 | uc str Underscore one character and move past it | |
c4737001 | 274 | ue str End underscore mode |
ef978bfe JB |
275 | ug num Number of garbage chars left by \fBus\fP or \fBue\fP (default 0) |
276 | ul bool Underline character overstrikes | |
277 | UP str (NP*) Move cursor up \fIn\^\fP lines | |
c4737001 KM |
278 | up str Upline (cursor up) |
279 | us str Start underscore mode | |
ef978bfe JB |
280 | vb str Visible bell (must not move cursor) |
281 | ve str Make cursor appear normal (undo \fBvs\fP/\fBvi\fP) | |
282 | vi str Make cursor invisible | |
283 | vs str Make cursor very visible | |
284 | vt num Virtual terminal number (not supported on all systems) | |
285 | wi str (N) Set current window | |
286 | ws num Number of columns in status line | |
287 | xb bool Beehive (f1=\s-2ESC\s0, f2=^C) | |
288 | xn bool Newline ignored after 80 cols (Concept) | |
289 | xo bool Terminal uses xoff/xon (\s-2DC3\s0/\s-2DC1\s0) handshaking | |
290 | xr bool (o) Return acts like \fBce cr nl\fP (Delta Data) | |
291 | xs bool Standout not erased by overwriting (Hewlett-Packard) | |
292 | xt bool Tabs ruin, magic \fBso\fP char (Teleray 1061) | |
293 | xx bool (o) Tektronix 4025 insert-line | |
c4737001 | 294 | .fi |
ef978bfe | 295 | .ta 8n +8n |
c4737001 KM |
296 | .PP |
297 | .B A Sample Entry | |
298 | .PP | |
299 | The following entry, which describes the Concept\-100, is among the more | |
300 | complex entries in the | |
ef978bfe | 301 | .I termcap\^ |
c4737001 | 302 | file as of this writing. |
c4737001 KM |
303 | .PP |
304 | .nf | |
ef978bfe JB |
305 | ca\||\|concept100\||\|c100\||\|concept\||\|c104\||\|concept100-4p\||\|HDS Concept\-100:\e |
306 | :al=3*\eE^R:am:bl=^G:cd=16*\eE^C:ce=16\eE^U:cl=2*^L:cm=\eEa%+ %+ :\e | |
307 | :co#80:.cr=9^M:db:dc=16\eE^A:dl=3*\eE^B:do=^J:ei=\eE\e200:eo:im=\eE^P:in:\e | |
308 | :ip=16*:is=\eEU\eEf\eE7\eE5\eE8\eEl\eENH\eEK\eE\e200\eEo&\e200\eEo\e47\eE:k1=\eE5:\e | |
309 | :k2=\eE6:k3=\eE7:kb=^h:kd=\eE<:ke=\eEx:kh=\eE?:kl=\eE>:kr=\eE=:ks=\eEX:\e | |
310 | :ku=\eE;:le=^H:li#24:mb=\eEC:me=\eEN\e200:mh=\eEE:mi:mk=\eEH:mp=\eEI:\e | |
311 | :mr=\eED:nd=\eE=:pb#9600:rp=0.2*\eEr%.%+ :se=\eEd\eEe:sf=^J:so=\eEE\eED:\e | |
312 | :.ta=8\et:te=\eEv \e200\e200\e200\e200\e200\e200\eEp\er\en:\e | |
313 | :ti=\eEU\eEv 8p\eEp\er:ue=\eEg:ul:up=\eE;:us=\eEG:\e | |
314 | :vb=\eEk\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\eEK:\e | |
315 | :ve=\eEw:vs=\eEW:vt#8:xn:\e | |
316 | :bs:cr=^M:dC#9:dT#8:nl=^J:ta=^I:pt: | |
c4737001 KM |
317 | .fi |
318 | .PP | |
319 | Entries may continue onto multiple lines by giving a \e as the last | |
ef978bfe | 320 | character of a line, and empty fields |
c4737001 KM |
321 | may be included for readability (here between the last field on a line |
322 | and the first field on the next). | |
ef978bfe JB |
323 | Comments may be included on lines beginning with \*(lq#\*(rq. |
324 | .br | |
325 | .ne 5 | |
c4737001 KM |
326 | .PP |
327 | .B Types of Capabilities | |
328 | .PP | |
ef978bfe JB |
329 | Capabilities in |
330 | .I termcap\^ | |
331 | are of three types: Boolean capabilities, | |
332 | which indicate particular features that the terminal has; | |
333 | numeric capabilities, | |
334 | giving the size of the display or the size of other attributes; | |
335 | and string capabilities, | |
336 | which give character sequences that can be used to perform particular | |
337 | terminal operations. | |
338 | All capabilities have two-letter codes. | |
339 | For instance, the fact that | |
340 | the Concept has | |
341 | .I automatic margins | |
342 | .RI ( i.e. , | |
343 | an automatic return and linefeed | |
344 | when the end of a line is reached) is indicated by the Boolean capability | |
345 | .BR am . | |
346 | Hence the description of the Concept includes | |
347 | .BR am . | |
348 | .PP | |
349 | Numeric capabilities are followed by the character `#' then the value. | |
350 | In the example above | |
351 | .BR co , | |
352 | which indicates the number of columns the display has, | |
c4737001 KM |
353 | gives the value `80' for the Concept. |
354 | .PP | |
ef978bfe JB |
355 | Finally, string-valued capabilities, such as |
356 | .B ce | |
357 | (clear-to-end-of-line | |
358 | sequence) are given by the two-letter code, an `=', then a string | |
359 | ending at the next following `:'. | |
360 | A delay in milliseconds may appear after | |
361 | the `=' in such a capability, | |
362 | which causes padding characters to be supplied by | |
363 | .I tputs\^ | |
364 | after the remainder of the string is sent to provide this delay. | |
365 | The delay can be either a number, | |
366 | .I e.g. | |
367 | `20', or a number followed by | |
368 | an `*', | |
369 | .IR i.e. , | |
370 | `3*'. | |
371 | An `*' indicates that the padding required is proportional | |
c4737001 | 372 | to the number of lines affected by the operation, and the amount given is |
ef978bfe JB |
373 | the per-affected-line padding required. |
374 | (In the case of insert-character, | |
375 | the factor is still the number of | |
376 | .I lines\^ | |
377 | affected; | |
378 | this is always 1 unless the terminal has | |
379 | .B in | |
380 | and the software uses it.) | |
381 | When an `*' is specified, it is sometimes useful to give a delay of the form | |
382 | `3.5' to specify a delay per line to tenths of milliseconds. | |
383 | (Only one decimal place is allowed.) | |
384 | .PP | |
385 | A number of escape sequences are provided in the string-valued capabilities | |
386 | for easy encoding of control characters there. | |
387 | .B \eE | |
388 | maps to an \s-2ESC\s0 | |
389 | character, | |
390 | .B ^X | |
391 | maps to a control-X for any appropriate X, | |
392 | and the sequences | |
393 | .B \en | |
394 | .B \er | |
395 | .B \et | |
396 | .B \eb | |
397 | .B \ef | |
398 | map to linefeed, return, tab, backspace, and formfeed, respectively. | |
399 | Finally, characters may be given as three octal digits after a | |
400 | .BR \e , | |
401 | and the characters | |
402 | .B ^ | |
403 | and | |
404 | .B \e | |
405 | may be given as | |
406 | .B \e^ | |
407 | and | |
408 | .BR \e\e . | |
409 | If it is necessary to place a | |
410 | .B : | |
411 | in a capability it must be escaped in | |
412 | octal as | |
413 | .BR \e072 . | |
414 | If it is necessary to place a \s-2NUL\s0 | |
415 | character in a string capability it | |
416 | must be encoded as | |
417 | .BR \e200 . | |
418 | (The routines that deal with | |
419 | .I termcap\^ | |
420 | use C strings and strip the high bits of the output very late, so that | |
421 | a | |
422 | .B \e200 | |
423 | comes out as a | |
424 | .B \e000 | |
425 | would.) | |
426 | .PP | |
427 | Sometimes individual capabilities must be commented out. | |
428 | To do this, put a period before the capability name. | |
429 | For example, see the first | |
430 | .B cr | |
431 | and | |
432 | .B ta | |
433 | in the example above. | |
c4737001 KM |
434 | .br |
435 | .ne 5 | |
436 | .PP | |
437 | .B Preparing Descriptions | |
438 | .PP | |
439 | We now outline how to prepare descriptions of terminals. | |
440 | The most effective way to prepare a terminal description is by imitating | |
441 | the description of a similar terminal in | |
ef978bfe | 442 | .I termcap\^ |
c4737001 KM |
443 | and to build up a description gradually, using partial descriptions |
444 | with | |
ef978bfe | 445 | .I vi\^ |
c4737001 KM |
446 | to check that they are correct. |
447 | Be aware that a very unusual terminal may expose deficiencies in | |
448 | the ability of the | |
ef978bfe | 449 | .I termcap\^ |
c4737001 KM |
450 | file to describe it |
451 | or bugs in | |
ef978bfe | 452 | .IR vi\^ . |
1e1561a8 JK |
453 | To easily test a new terminal description you are working on |
454 | you can put it in your home directory in a file called | |
455 | .I .termcap\^ | |
456 | and programs will look there before looking in | |
ef978bfe | 457 | .IR /etc/termcap\^ . |
1e1561a8 JK |
458 | You can also set the environment variable |
459 | .B | |
460 | .SM TERMPATH | |
461 | to a list of absolute file pathnames (separated by spaces or colons), | |
462 | one of which contains the description you are working on, | |
463 | and programs will search them in the order listed, and nowhere else. | |
464 | See | |
465 | .IR termcap\^ (3X). | |
466 | The | |
ef978bfe JB |
467 | .B |
468 | .SM TERMCAP | |
1e1561a8 | 469 | environment variable is usually set to the |
ef978bfe JB |
470 | .I termcap\^ |
471 | entry itself | |
1e1561a8 | 472 | to avoid reading files when starting up a program. |
ef978bfe JB |
473 | .PP |
474 | To get the padding for insert-line right | |
475 | (if the terminal manufacturer did not document it), | |
476 | a severe test is to use | |
477 | .I vi\^ | |
478 | to edit | |
479 | .I /etc/passwd\^ | |
480 | at 9600 baud, delete roughly 16 lines from the middle of the screen, | |
481 | then hit the `u' key several times quickly. | |
482 | If the display messes up, more padding is usually needed. | |
483 | A similar test can be used for insert-character. | |
484 | .br | |
485 | .ne 5 | |
486 | .PP | |
487 | .B Basic Capabilities | |
488 | .PP | |
489 | The number of columns on each line of the display is given by the | |
490 | .B co | |
491 | numeric capability. | |
492 | If the display is a \s-1CRT\s0, then the | |
493 | number of lines on the screen is given by the | |
494 | .B li | |
495 | capability. | |
496 | If the display wraps around to the beginning of the next line when | |
497 | the cursor reaches the right margin, then it should have the | |
498 | .B am | |
499 | capability. | |
500 | If the terminal can clear its screen, | |
501 | the code to do this is given by the | |
502 | .B cl | |
503 | string capability. | |
504 | If the terminal overstrikes | |
505 | (rather than clearing the position when a character is overwritten), | |
506 | it should have the | |
507 | .B os | |
508 | capability. | |
509 | If the terminal is a printing terminal, | |
510 | with no soft copy unit, | |
511 | give it both | |
512 | .B hc | |
513 | and | |
514 | .BR os . | |
515 | .RB ( os | |
516 | applies to storage scope terminals, | |
517 | such as the Tektronix 4010 series, | |
518 | as well as to hard copy and | |
519 | .SM APL | |
520 | terminals.) | |
521 | If there is a code to move the cursor to the left edge of the current row, | |
522 | give this as | |
523 | .BR cr . | |
524 | (Normally this will be carriage-return, | |
525 | .BR ^M .) | |
526 | If there is a code to produce an audible signal (bell, beep, | |
527 | .IR etc.\^ ), | |
528 | give this as | |
529 | .BR bl . | |
530 | .PP | |
531 | If there is a code (such as backspace) | |
532 | to move the cursor one position to the left, | |
533 | that capability should be given as | |
534 | .BR le . | |
535 | Similarly, | |
536 | codes to move to the right, up, and down | |
537 | should be given as | |
538 | .BR nd , | |
539 | .BR up , | |
540 | and | |
541 | .BR do , | |
542 | respectively. | |
543 | These | |
544 | .I local cursor motions\^ | |
545 | should not alter the text they pass over; | |
546 | for example, you would not normally use | |
547 | \*(lqnd=\ \*(rq | |
548 | unless the terminal has the | |
549 | .B os | |
550 | capability, | |
551 | because the space would erase the character moved over. | |
c4737001 KM |
552 | .PP |
553 | A very important point here is that the local cursor motions encoded | |
554 | in | |
ef978bfe JB |
555 | .I termcap\^ |
556 | have undefined behavior at the left and top edges of a | |
557 | .SM CRT | |
558 | display. | |
559 | Programs should never attempt to backspace around the left edge, | |
560 | unless | |
561 | .B bw | |
562 | is given, and never attempt to go up off the top | |
563 | using local cursor motions. | |
564 | .PP | |
565 | In order to scroll text up, | |
566 | a program goes to the bottom left corner of the screen and sends the | |
567 | .B sf | |
568 | (index) string. | |
569 | To scroll text down, | |
570 | a program goes to the top left corner of the screen and sends the | |
571 | .B sr | |
572 | (reverse index) string. | |
573 | The strings | |
574 | .B sf | |
575 | and | |
576 | .B sr | |
577 | have undefined behavior | |
578 | when not on their respective corners of the screen. | |
579 | Parameterized versions of the scrolling sequences are | |
580 | .B SF | |
581 | and | |
582 | .BR SR , | |
583 | which have the same semantics as | |
584 | .B sf | |
585 | and | |
586 | .B sr | |
587 | except that they take one parameter | |
588 | and scroll that many lines. | |
589 | They also have undefined behavior | |
590 | except at the appropriate corner of the screen. | |
591 | .PP | |
592 | The | |
593 | .B am | |
594 | capability tells whether the cursor sticks at the right | |
595 | edge of the screen when text is output there, | |
596 | but this does not necessarily apply to | |
597 | .B nd | |
598 | from the last column. | |
599 | Leftward local motion is defined from the left edge only when | |
600 | .B bw | |
601 | is given; then an | |
602 | .B le | |
603 | from the left edge will move to the right edge of the previous row. | |
604 | This is useful for drawing a box around the edge of the screen, | |
605 | for example. | |
606 | If the terminal has switch-selectable automatic margins, | |
c4737001 | 607 | the |
ef978bfe JB |
608 | .I termcap\^ |
609 | description usually assumes that this feature is on, | |
610 | .IR i.e. , | |
611 | .BR am . | |
612 | If the terminal has a command | |
613 | that moves to the first column of the next line, | |
614 | that command can be given as | |
615 | .B nw | |
616 | (newline). | |
617 | It is permissible for this to clear the remainder of the current line, | |
618 | so if the terminal has no correctly-working \s-2CR\s0 and \s-2LF\s0 | |
619 | it may still be possible to craft a working | |
620 | .B nw | |
621 | out of one or both of them. | |
c4737001 KM |
622 | .PP |
623 | These capabilities suffice to describe hardcopy and \*(lqglass-tty\*(rq terminals. | |
ef978bfe | 624 | Thus the Teletype model 33 is described as |
c4737001 | 625 | .PP |
ef978bfe JB |
626 | .nf |
627 | T3\||\|tty33\||\|33\||\|tty\||\|Teletype model 33:\e | |
628 | :bl=^G:co#72:cr=^M:do=^J:hc:os: | |
629 | .fi | |
c4737001 | 630 | .PP |
ef978bfe | 631 | and the Lear Siegler \s-1ADM\s0\-3 is described as |
c4737001 | 632 | .PP |
ef978bfe JB |
633 | .nf |
634 | l3\||\|adm3\||\|3\||\|LSI \s-1ADM\s0-3:\e | |
635 | :am:bl=^G:cl=^Z:co#80:cr=^M:do=^J:le=^H:li#24:sf=^J: | |
636 | .fi | |
637 | .br | |
638 | .ne 5 | |
c4737001 | 639 | .PP |
ef978bfe | 640 | .B Parameterized Strings |
c4737001 | 641 | .PP |
ef978bfe JB |
642 | Cursor addressing and other strings requiring parameters |
643 | are described by a | |
644 | parameterized string capability, with | |
645 | .IR printf\^ (3S)-like | |
646 | escapes | |
647 | .B %x | |
648 | in it, | |
c4737001 | 649 | while other characters are passed through unchanged. |
ef978bfe JB |
650 | For example, to address the cursor the |
651 | .B cm | |
652 | capability is given, using two parameters: the row and column to move to. | |
653 | (Rows and columns are numbered from zero and refer to the physical screen | |
654 | visible to the user, not to any unseen memory. | |
655 | If the terminal has memory-relative cursor addressing, | |
656 | that can be indicated by an analogous | |
657 | .B CM | |
658 | capability.) | |
659 | .PP | |
660 | The | |
661 | .B % | |
662 | encodings have the following meanings: | |
c4737001 KM |
663 | .PP |
664 | .DT | |
665 | .nf | |
ef978bfe JB |
666 | %% output `%' |
667 | %d output value as in \fIprintf\^\fP %d | |
668 | %2 output value as in \fIprintf\^\fP %2d | |
669 | %3 output value as in \fIprintf\^\fP %3d | |
670 | %. output value as in \fIprintf\^\fP %c | |
671 | %+\fIx\fP add \fIx\^\fP to value, then do %. | |
672 | %>\fIxy\fP if value > \fIx\^\fP then add \fIy\^\fP, no output | |
673 | %r reverse order of two parameters, no output | |
674 | %i increment by one, no output | |
675 | %n exclusive-or all parameters with 0140 (Datamedia 2500) | |
676 | %B BCD (16*(value/10)) + (value%10), no output | |
677 | %D Reverse coding (value \- 2*(value%16)), no output (Delta Data) | |
c4737001 KM |
678 | .fi |
679 | .PP | |
ef978bfe JB |
680 | Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, needs |
681 | to be sent \*(lq\eE&a12c03Y\*(rq padded for 6 milliseconds. | |
682 | Note that the order | |
683 | of the row and column coordinates is reversed here | |
684 | and that the row and column | |
685 | are sent as two-digit integers. | |
686 | Thus its | |
687 | .B cm | |
688 | capability is \*(lqcm=6\eE&%r%2c%2Y\*(rq. | |
689 | .PP | |
dc9699ea JK |
690 | The Datamedia 2500 needs the current row and column sent |
691 | encoded in binary using \*(lq%.\*(rq. | |
ef978bfe JB |
692 | Terminals that use \*(lq%.\*(rq need to be able to |
693 | backspace the cursor | |
694 | .RB ( le ) | |
695 | and to move the cursor up one line on the screen | |
696 | .RB ( up ). | |
697 | This is necessary because it is not always safe to transmit | |
698 | .BR \en , | |
699 | .BR ^D , | |
700 | and | |
701 | .BR \er , | |
702 | as the system may change or discard them. | |
703 | (Programs using | |
704 | .I termcap\^ | |
705 | must set terminal modes so that tabs are not expanded, so | |
706 | .B \et | |
707 | is safe to send. | |
708 | This turns out to be essential for the Ann Arbor 4080.) | |
709 | .PP | |
710 | A final example is the Lear Siegler \s-1ADM\s0\-3a, | |
711 | which offsets row and column | |
712 | by a blank character, thus \*(lqcm=\eE=%+ %+ \*(rq. | |
713 | .PP | |
714 | Row or column absolute cursor addressing | |
715 | can be given as single parameter capabilities | |
716 | .B ch | |
717 | (horizontal position absolute) and | |
718 | .B cv | |
719 | (vertical position absolute). | |
720 | Sometimes these are shorter than the more general two-parameter sequence | |
721 | (as with the Hewlett-Packard 2645) and can be used in preference to | |
722 | .BR cm . | |
723 | If there are parameterized local motions | |
724 | .RI ( e.g. , | |
725 | move | |
726 | .I n\^ | |
727 | positions to the right) | |
728 | these can be given as | |
729 | .BR DO , | |
730 | .BR LE , | |
731 | .BR RI , | |
732 | and | |
733 | .B UP | |
734 | with a single parameter indicating how many positions to move. | |
735 | These are primarily useful if the terminal does not have | |
736 | .BR cm , | |
737 | such as the Tektronix 4025. | |
738 | .br | |
739 | .ne 5 | |
740 | .PP | |
741 | .B Cursor Motions | |
742 | .PP | |
743 | If the terminal has a fast way to home the cursor | |
744 | (to the very upper left corner of the screen), this can be given as | |
745 | .BR ho . | |
746 | Similarly, a fast way of getting to the lower left-hand corner | |
747 | can be given as | |
748 | .BR ll ; | |
749 | this may involve going up with | |
750 | .B up | |
c4737001 | 751 | from the home position, |
ef978bfe JB |
752 | but a program should never do this itself (unless |
753 | .B ll | |
754 | does), because it can | |
755 | make no assumption about the effect of moving up from the home position. | |
756 | Note that the home position is the same as | |
757 | cursor address (0,0): to the top left corner of the screen, not of memory. | |
758 | (Therefore, the \*(lq\eEH\*(rq sequence on Hewlett-Packard terminals | |
759 | cannot be used for | |
760 | .BR ho .) | |
761 | .br | |
762 | .ne 5 | |
c4737001 | 763 | .PP |
ef978bfe | 764 | .B Area Clears |
c4737001 KM |
765 | .PP |
766 | If the terminal can clear from the current position to the end of the | |
ef978bfe JB |
767 | line, leaving the cursor where it is, this should be given as |
768 | .BR ce . | |
c4737001 | 769 | If the terminal can clear from the current position to the end of the |
ef978bfe JB |
770 | display, this should be given as |
771 | .BR cd . | |
772 | .B cd | |
773 | must only be invoked from the first column of a line. | |
774 | (Therefore, | |
775 | it can be simulated by a request to delete a large number of lines, | |
776 | if a true | |
777 | .B cd | |
778 | is not available.) | |
779 | .br | |
780 | .ne 5 | |
c4737001 | 781 | .PP |
ef978bfe | 782 | .B Insert/Delete Line |
c4737001 | 783 | .PP |
ef978bfe JB |
784 | If the terminal can open a new blank line |
785 | before the line containing the cursor, | |
786 | this should be given as | |
787 | .BR al ; | |
788 | this must be invoked only from the first | |
789 | position of a line. | |
790 | The cursor must then appear at the left of the newly blank line. | |
791 | If the terminal can delete the line that the cursor is on, this | |
792 | should be given as | |
793 | .BR dl ; | |
794 | this must only be used from the first position on | |
c4737001 | 795 | the line to be deleted. |
ef978bfe JB |
796 | Versions of |
797 | .B al | |
798 | and | |
799 | .B dl | |
800 | which take a single parameter | |
801 | and insert or delete that many lines | |
802 | can be given as | |
803 | .B AL | |
804 | and | |
805 | .BR DL . | |
806 | If the terminal has a settable scrolling region | |
807 | (like the VT100), | |
808 | the command to set this can be described with the | |
809 | .B cs | |
810 | capability, | |
811 | which takes two parameters: the top and bottom lines of the scrolling region. | |
812 | The cursor position is, alas, undefined after using this command. | |
813 | It is possible to get the effect of insert or delete line | |
814 | using this command \(em the | |
815 | .B sc | |
816 | and | |
817 | .B rc | |
818 | (save and restore cursor) commands are also useful. | |
819 | Inserting lines at the top or bottom of the screen can also be done using | |
820 | .B sr | |
821 | or | |
822 | .B sf | |
823 | on many terminals without a true insert/delete line, | |
824 | and is often faster even on terminals with those features. | |
825 | .PP | |
826 | If the terminal has the ability to define a window as part of memory | |
827 | which all commands affect, it should be given as the parameterized string | |
828 | .BR wi . | |
829 | The four parameters are the starting and ending lines in memory | |
830 | and the starting and ending columns in memory, in that order. | |
831 | (This | |
832 | .I terminfo\^ | |
833 | capability is described for completeness. | |
834 | It is unlikely that any | |
835 | .IR termcap\^ -using | |
836 | program will support it.) | |
837 | .PP | |
838 | If the terminal can retain display memory above the screen, then the | |
839 | .B da | |
840 | capability should be given; | |
841 | if display memory can be retained | |
842 | below, then | |
843 | .B db | |
844 | should be given. | |
845 | These indicate | |
846 | that deleting a line or scrolling may bring non-blank lines up from below | |
847 | or that scrolling back with | |
848 | .B sr | |
849 | may bring down non-blank lines. | |
850 | .br | |
851 | .ne 5 | |
c4737001 | 852 | .PP |
ef978bfe | 853 | .B Insert/Delete Character |
c4737001 KM |
854 | .PP |
855 | There are two basic kinds of intelligent terminals with respect to | |
ef978bfe JB |
856 | insert/delete character that can be described using |
857 | .IR termcap\^ . | |
c4737001 KM |
858 | The most common insert/delete character operations affect only the characters |
859 | on the current line and shift characters off the end of the line rigidly. | |
ef978bfe | 860 | Other terminals, such as the Concept\-100 and the Perkin Elmer Owl, make |
c4737001 KM |
861 | a distinction between typed and untyped blanks on the screen, shifting |
862 | upon an insert or delete only to an untyped blank on the screen which is | |
ef978bfe JB |
863 | either eliminated or expanded to two untyped blanks. |
864 | You can determine | |
865 | the kind of terminal you have by clearing the screen then typing | |
866 | text separated by cursor motions. | |
867 | Type \*(lqabc\ \ \ \ def\*(rq using local | |
c4737001 KM |
868 | cursor motions (not spaces) between the \*(lqabc\*(rq and the \*(lqdef\*(rq. |
869 | Then position the cursor before the \*(lqabc\*(rq and put the terminal in insert | |
ef978bfe JB |
870 | mode. |
871 | If typing characters causes the rest of the line to shift | |
c4737001 | 872 | rigidly and characters to fall off the end, then your terminal does |
ef978bfe JB |
873 | not distinguish between blanks and untyped positions. |
874 | If the \*(lqabc\*(rq | |
c4737001 | 875 | shifts over to the \*(lqdef\*(rq which then move together around the end of the |
ef978bfe JB |
876 | current line and onto the next as you insert, then you have the second type of |
877 | terminal and should give the capability \fBin\fP, which stands for | |
878 | \*(lqinsert null\*(rq. | |
879 | While these are two logically separate attributes | |
880 | (one line | |
881 | .I vs. | |
882 | multi-line insert mode, | |
883 | and special treatment of untyped spaces), | |
884 | we have seen no terminals whose insert | |
885 | mode cannot be described with the single attribute. | |
886 | .PP | |
887 | .I Termcap\^ | |
888 | can describe both terminals that have an insert mode and terminals | |
889 | that send a simple sequence to open a blank position on the current line. | |
890 | Give as | |
891 | .B im | |
892 | the sequence to get into insert mode. | |
893 | Give as | |
894 | .B ei | |
895 | the sequence to leave insert mode. | |
896 | Now give as | |
897 | .B ic | |
898 | any sequence that needs to be sent just before | |
899 | each character to be inserted. | |
900 | Most terminals with a true insert mode | |
901 | will not give | |
902 | .BR ic ; | |
903 | terminals that use a sequence to open a screen | |
904 | position should give it here. | |
905 | (If your terminal has both, | |
906 | insert mode is usually preferable to | |
907 | .BR ic . | |
908 | Do not give both unless the terminal actually requires both to be used | |
909 | in combination.) | |
910 | If post-insert padding is needed, give this as a number of milliseconds | |
911 | in | |
912 | .B ip | |
913 | (a string option). | |
914 | Any other sequence that may need to be | |
915 | sent after insertion of a single character can also be given in | |
916 | .BR ip . | |
917 | If your terminal needs to be placed into an `insert mode' | |
918 | and needs a special code preceding each inserted character, | |
919 | then both | |
920 | .BR im / ei | |
921 | and | |
922 | .B ic | |
923 | can be given, and both will be used. | |
924 | The | |
925 | .B IC | |
926 | capability, with one parameter | |
927 | .IR n\^ , | |
928 | will repeat the effects of | |
929 | .B ic | |
930 | .I n\^ | |
931 | times. | |
c4737001 KM |
932 | .PP |
933 | It is occasionally necessary to move around while in insert mode | |
ef978bfe JB |
934 | to delete characters on the same line |
935 | .RI ( e.g. , | |
936 | if there is a tab after | |
937 | the insertion position). | |
938 | If your terminal allows motion while in | |
939 | insert mode, you can give the capability | |
940 | .B mi | |
941 | to speed up inserting | |
942 | in this case. | |
943 | Omitting | |
944 | .B mi | |
945 | will affect only speed. | |
946 | Some terminals | |
947 | (notably Datamedia's) must not have | |
948 | .B mi | |
949 | because of the way their | |
c4737001 KM |
950 | insert mode works. |
951 | .PP | |
ef978bfe JB |
952 | Finally, you can specify |
953 | .B dc | |
954 | to delete a single character, | |
955 | .B DC | |
956 | with one parameter | |
957 | .I n\^ | |
958 | to delete | |
959 | .I n\^ | |
960 | characters, | |
961 | and delete mode by giving | |
962 | .B dm | |
963 | and | |
964 | .B ed | |
965 | to enter and exit delete mode | |
966 | (which is any mode the terminal needs to be placed in for | |
967 | .B dc | |
968 | to work). | |
969 | .br | |
970 | .ne 5 | |
c4737001 | 971 | .PP |
ef978bfe | 972 | .B Highlighting, Underlining, and Visible Bells |
c4737001 | 973 | .PP |
ef978bfe JB |
974 | If your terminal has one or more kinds of display attributes, |
975 | these can be represented in a number of different ways. | |
976 | You should choose one display form as | |
977 | .IR "standout mode" , | |
978 | representing a good high-contrast, easy-on-the-eyes format | |
979 | for highlighting error messages and other attention getters. | |
980 | (If you have a choice, reverse video plus half-bright is good, | |
981 | or reverse video alone.) | |
982 | The sequences to enter and exit standout mode | |
983 | are given as | |
984 | .B so | |
985 | and | |
986 | .BR se , | |
987 | respectively. | |
c4737001 | 988 | If the code to change into or out of standout |
ef978bfe | 989 | mode leaves one or even two blank spaces or garbage characters on the screen, |
c4737001 | 990 | as the TVI 912 and Teleray 1061 do, |
ef978bfe JB |
991 | then |
992 | .B sg | |
993 | should be given to tell how many characters are left. | |
c4737001 | 994 | .PP |
ef978bfe JB |
995 | Codes to begin underlining and end underlining can be given as |
996 | .B us | |
997 | and | |
998 | .BR ue , | |
999 | respectively. | |
1000 | Underline mode change garbage is specified by | |
1001 | .BR ug , | |
1002 | similar to | |
1003 | .BR sg . | |
c4737001 | 1004 | If the terminal has a code to underline the current character and move |
ef978bfe | 1005 | the cursor one position to the right, |
c4737001 | 1006 | such as the Microterm Mime, |
ef978bfe JB |
1007 | this can be given as |
1008 | .BR uc . | |
c4737001 | 1009 | .PP |
ef978bfe JB |
1010 | Other capabilities to enter various highlighting modes include |
1011 | .B mb | |
1012 | (blinking), | |
1013 | .B md | |
1014 | (bold or extra bright), | |
1015 | .B mh | |
1016 | (dim or half-bright), | |
1017 | .B mk | |
1018 | (blanking or invisible text), | |
1019 | .B mp | |
1020 | (protected), | |
1021 | .B mr | |
1022 | (reverse video), | |
1023 | .B me | |
1024 | (turn off | |
1025 | .I all | |
1026 | attribute modes), | |
1027 | .B as | |
1028 | (enter alternate character set mode), and | |
1029 | .B ae | |
1030 | (exit alternate character set mode). | |
1031 | Turning on any of these modes singly may or may not turn off other modes. | |
1032 | .PP | |
1033 | If there is a sequence to set arbitrary combinations of mode, | |
1034 | this should be given as | |
1035 | .B sa | |
1036 | (set attributes), taking 9 parameters. | |
1037 | Each parameter is either 0 or 1, | |
1038 | as the corresponding attributes is on or off. | |
1039 | The 9 parameters are, in order: standout, underline, reverse, blink, | |
1040 | dim, bold, blank, protect, and alternate character set. | |
1041 | Not all modes need be supported by | |
1042 | .BR sa , | |
1043 | only those for which corresponding attribute commands exist. | |
1044 | (It is unlikely that a | |
1045 | .IR termcap\^ -using | |
1046 | program will support this capability, which is defined for compatibility | |
1047 | with | |
1048 | .IR terminfo\^ .) | |
1049 | .PP | |
1050 | Terminals with the \*(lqmagic cookie\*(rq glitches | |
1051 | .RB ( sg | |
1052 | and | |
1053 | .BR ug ), | |
1054 | rather than maintaining extra attribute bits for each character cell, | |
1055 | instead deposit special \*(lqcookies\*(rq, | |
1056 | or \*(lqgarbage characters\*(rq, | |
1057 | when they receive mode-setting sequences, | |
1058 | which affect the display algorithm. | |
1059 | .PP | |
1060 | Some terminals, | |
1061 | such as the Hewlett-Packard 2621, | |
1062 | automatically leave standout | |
1063 | mode when they move to a new line or when the cursor is addressed. | |
1064 | Programs using standout mode | |
1065 | should exit standout mode on such terminals | |
1066 | before moving the cursor or sending a newline. | |
1067 | On terminals where this is not a problem, | |
1068 | the | |
1069 | .B ms | |
1070 | capability should be present | |
1071 | to say that this overhead is unnecessary. | |
c4737001 KM |
1072 | .PP |
1073 | If the terminal has | |
ef978bfe JB |
1074 | a way of flashing the screen to indicate an error quietly |
1075 | (a bell replacement), | |
c4737001 | 1076 | this can be given as |
ef978bfe JB |
1077 | .BR vb ; |
1078 | it must not move the cursor. | |
c4737001 | 1079 | .PP |
ef978bfe JB |
1080 | If the cursor needs to be made more visible than normal |
1081 | when it is not on the bottom line | |
1082 | (to change, for example, a non-blinking underline into an easier-to-find | |
1083 | block or blinking underline), | |
1084 | give this sequence as | |
1085 | .BR vs . | |
1086 | If there is a way to make the cursor completely invisible, give that as | |
1087 | .BR vi . | |
1088 | The capability | |
1089 | .BR ve , | |
1090 | which undoes the effects of both of these modes, | |
1091 | should also be given. | |
c4737001 | 1092 | .PP |
ef978bfe | 1093 | If your terminal correctly displays underlined characters |
c4737001 KM |
1094 | (with no special codes needed) |
1095 | even though it does not overstrike, | |
ef978bfe JB |
1096 | then you should give the capability |
1097 | .BR ul . | |
c4737001 | 1098 | If overstrikes are erasable with a blank, |
ef978bfe JB |
1099 | this should be indicated by giving |
1100 | .BR eo . | |
1101 | .br | |
1102 | .ne 5 | |
c4737001 KM |
1103 | .PP |
1104 | .B Keypad | |
1105 | .PP | |
1106 | If the terminal has a keypad that transmits codes when the keys are pressed, | |
ef978bfe JB |
1107 | this information can be given. |
1108 | Note that it is not possible to handle | |
1109 | terminals where the keypad only works in local mode | |
1110 | (this applies, for example, to the unshifted Hewlett-Packard 2621 keys). | |
c4737001 | 1111 | If the keypad can be set to transmit or not transmit, |
ef978bfe JB |
1112 | give these codes as |
1113 | .B ks | |
1114 | and | |
1115 | .BR ke . | |
c4737001 | 1116 | Otherwise the keypad is assumed to always transmit. |
ef978bfe JB |
1117 | The codes sent by the left-arrow, right-arrow, up-arrow, down-arrow, |
1118 | and home keys can be given as | |
1119 | .BR kl , | |
1120 | .BR kr , | |
1121 | .BR ku , | |
1122 | .BR kd , | |
1123 | and | |
1124 | .BR kh , | |
1125 | respectively. | |
c4737001 | 1126 | If there are function keys such as f0, f1, ..., f9, the codes they send |
ef978bfe JB |
1127 | can be given as |
1128 | .BR k0 , | |
1129 | .BR k1 , "" ..., | |
1130 | .BR k9 . | |
c4737001 | 1131 | If these keys have labels other than the default f0 through f9, the labels |
ef978bfe JB |
1132 | can be given as |
1133 | .BR l0 , | |
1134 | .BR l1 , "" ..., | |
1135 | .BR l9 . | |
1136 | The codes transmitted by certain other special keys can be given: | |
1137 | .B kH | |
1138 | (home down), | |
1139 | .B kb | |
1140 | (backspace), | |
1141 | .B ka | |
1142 | (clear all tabs), | |
1143 | .B kt | |
1144 | (clear the tab stop in this column), | |
1145 | .B kC | |
1146 | (clear screen or erase), | |
1147 | .B kD | |
1148 | (delete character), | |
1149 | .B kL | |
1150 | (delete line), | |
1151 | .B kM | |
1152 | (exit insert mode), | |
1153 | .B kE | |
1154 | (clear to end of line), | |
1155 | .B kS | |
1156 | (clear to end of screen), | |
1157 | .B kI | |
1158 | (insert character or enter insert mode), | |
1159 | .B kA | |
1160 | (insert line), | |
1161 | .B kN | |
1162 | (next page), | |
1163 | .B kP | |
1164 | (previous page), | |
1165 | .B kF | |
1166 | (scroll forward/down), | |
1167 | .B kR | |
1168 | (scroll backward/up), and | |
1169 | .B kT | |
1170 | (set a tab stop in this column). | |
1171 | In addition, if the keypad has a 3 by 3 array of keys | |
1172 | including the four arrow keys, then the other five keys can be given as | |
1173 | .BR K1 , | |
1174 | .BR K2 , | |
1175 | .BR K3 , | |
1176 | .BR K4 , | |
1177 | and | |
1178 | .BR K5 . | |
1179 | These keys are useful when the effects of a 3 by 3 directional pad are needed. | |
1180 | The obsolete | |
1181 | .B ko | |
1182 | capability formerly used to describe \*(lqother\*(rq function keys has been | |
1183 | completely supplanted by the above capabilities. | |
c4737001 KM |
1184 | .PP |
1185 | The | |
1186 | .B ma | |
ef978bfe JB |
1187 | entry is also used to indicate arrow keys on terminals that have |
1188 | single-character arrow keys. | |
1189 | It is obsolete but still in use in | |
1190 | version 2 of | |
1191 | .I vi\^ | |
1192 | which must be run on some minicomputers due to | |
c4737001 KM |
1193 | memory limitations. |
1194 | This field is redundant with | |
ef978bfe JB |
1195 | .BR kl , |
1196 | .BR kr , | |
1197 | .BR ku , | |
1198 | .BR kd , | |
1199 | and | |
1200 | .BR kh . | |
c4737001 | 1201 | It consists of groups of two characters. |
ef978bfe JB |
1202 | In each group, the first character is what an arrow key sends, and the |
1203 | second character is the corresponding | |
1204 | .I vi\^ | |
1205 | command. | |
c4737001 KM |
1206 | These commands are |
1207 | .B h | |
1208 | for | |
1209 | .BR kl , | |
1210 | .B j | |
1211 | for | |
1212 | .BR kd , | |
1213 | .B k | |
1214 | for | |
1215 | .BR ku , | |
1216 | .B l | |
1217 | for | |
1218 | .BR kr , | |
1219 | and | |
1220 | .B H | |
1221 | for | |
1222 | .BR kh . | |
ef978bfe | 1223 | For example, the Mime would have \*(lqma=^Hh^Kj^Zk^Xl\*(rq |
c4737001 | 1224 | indicating arrow keys left (^H), down (^K), up (^Z), and right (^X). |
ef978bfe JB |
1225 | (There is no home key on the Mime.) |
1226 | .br | |
1227 | .ne 5 | |
1228 | .PP | |
1229 | .B Tabs and Initialization | |
1230 | .PP | |
1231 | If the terminal needs to be in a special mode when running | |
1232 | a program that uses these capabilities, | |
1233 | the codes to enter and exit this mode can be given as | |
1234 | .B ti | |
1235 | and | |
1236 | .BR te . | |
1237 | This arises, for example, from terminals like the Concept with more than | |
1238 | one page of memory. | |
1239 | If the terminal has only memory-relative cursor addressing and not | |
1240 | screen-relative cursor addressing, | |
1241 | a screen-sized window must be fixed into | |
1242 | the display for cursor addressing to work properly. | |
1243 | This is also used for the Tektronix 4025, where | |
1244 | .B ti | |
1245 | sets the command character to be the one used by | |
1246 | .IR termcap\^ . | |
1247 | .PP | |
1248 | Other capabilities | |
1249 | include | |
1250 | .BR is , | |
1251 | an initialization string for the terminal, | |
1252 | and | |
1253 | .BR if , | |
1254 | the name of a file containing long initialization strings. | |
1255 | These strings are expected to set the terminal into modes | |
1256 | consistent with the rest of the | |
1257 | .I termcap\^ | |
1258 | description. | |
1259 | They are normally sent to the terminal by the | |
1260 | .I tset\^ | |
1261 | program each time the user logs in. | |
1262 | They will be printed in the following order: | |
1263 | .BR is ; | |
1264 | setting tabs using | |
1265 | .B ct | |
1266 | and | |
1267 | .BR st ; | |
1268 | and finally | |
1269 | .BR if . | |
1270 | .RI ( Terminfo\^ | |
1271 | uses | |
1272 | .B i1-i2 | |
1273 | instead of | |
1274 | .B is | |
1275 | and runs the program | |
1276 | .B iP | |
1277 | and prints | |
1278 | .B i3 | |
1279 | after the other initializations.) | |
1280 | A pair of sequences that does a harder reset from a totally unknown state | |
1281 | can be analogously given as | |
1282 | .B rs | |
1283 | and | |
1284 | .BR if . | |
1285 | These strings are output by the | |
1286 | .I reset\^ | |
1287 | program, which is used when the terminal gets into a wedged state. | |
1288 | .RI ( Terminfo\^ | |
1289 | uses | |
1290 | .B r1-r3 | |
1291 | instead of | |
1292 | .BR rs .) | |
1293 | Commands are normally placed in | |
1294 | .B rs | |
1295 | and | |
1296 | .B rf | |
1297 | only if they produce annoying effects on the screen and are not necessary | |
1298 | when logging in. | |
1299 | For example, the command to set the VT100 into 80-column mode | |
1300 | would normally be part of | |
1301 | .BR is , | |
1302 | but it causes an annoying glitch of the screen and is not normally needed | |
1303 | since the terminal is usually already in 80-column mode. | |
1304 | .PP | |
1305 | If the terminal has hardware tabs, | |
1306 | the command to advance to the next tab stop can be given as | |
1307 | .B ta | |
1308 | (usually | |
1309 | .BR ^I ). | |
1310 | A \*(lqbacktab\*(rq command which moves leftward to the previous tab stop | |
1311 | can be given as | |
1312 | .BR bt . | |
1313 | By convention, | |
1314 | if the terminal driver modes indicate that tab stops are being expanded | |
1315 | by the computer rather than being sent to the terminal, | |
1316 | programs should not use | |
1317 | .B ta | |
1318 | or | |
1319 | .B bt | |
1320 | even if they are present, | |
1321 | since the user may not have the tab stops properly set. | |
1322 | If the terminal has hardware tabs that are initially set every | |
1323 | .I n\^ | |
1324 | positions when the terminal is powered up, then the numeric parameter | |
1325 | .B it | |
1326 | is given, showing the number of positions between tab stops. | |
1327 | This is normally used by the | |
1328 | .I tset\^ | |
1329 | command to determine whether to set the driver mode for hardware tab | |
1330 | expansion, and whether to set the tab stops. | |
1331 | If the terminal has tab stops that can be saved in nonvolatile memory, the | |
1332 | .I termcap\^ | |
1333 | description can assume that they are properly set. | |
1334 | .PP | |
1335 | If there are commands to set and clear tab stops, they can be given as | |
1336 | .B ct | |
1337 | (clear all tab stops) and | |
1338 | .B st | |
1339 | (set a tab stop in the current column of every row). | |
1340 | If a more complex sequence is needed to set the tabs than can be | |
1341 | described by this, the sequence can be placed in | |
1342 | .B is | |
1343 | or | |
1344 | .BR if . | |
1345 | .br | |
1346 | .ne 5 | |
1347 | .PP | |
1348 | .B Delays | |
1349 | .PP | |
1350 | Certain capabilities control padding in the terminal driver. | |
1351 | These are primarily needed by hardcopy terminals and are used by the | |
1352 | .I tset\^ | |
1353 | program to set terminal driver modes appropriately. | |
1354 | Delays embedded in the capabilities | |
1355 | .BR cr , | |
1356 | .BR sf , | |
1357 | .BR le , | |
1358 | .BR ff , | |
1359 | and | |
1360 | .B ta | |
1361 | will cause the appropriate delay bits to be set in the terminal driver. | |
1362 | If | |
1363 | .B pb | |
1364 | (padding baud rate) is given, these values can be ignored at baud rates | |
1365 | below the value of | |
1366 | .BR pb . | |
1367 | For 4.2BSD | |
1368 | .IR tset\^ , | |
1369 | the delays are given as numeric capabilities | |
1370 | .BR dC , | |
1371 | .BR dN , | |
1372 | .BR dB , | |
1373 | .BR dF , | |
1374 | and | |
1375 | .BR dT | |
1376 | instead. | |
1377 | .br | |
1378 | .ne 5 | |
c4737001 KM |
1379 | .PP |
1380 | .B Miscellaneous | |
1381 | .PP | |
ef978bfe JB |
1382 | If the terminal requires other than a \s-2NUL\s0 (zero) character as a pad, |
1383 | this can be given as | |
1384 | .BR pc . | |
1385 | Only the first character of the | |
1386 | .B pc | |
1387 | string is used. | |
1388 | .PP | |
1389 | If the terminal has commands to save and restore the position of the | |
1390 | cursor, give them as | |
1391 | .B sc | |
1392 | and | |
1393 | .BR rc . | |
1394 | .PP | |
1395 | If the terminal has an extra \*(lqstatus line\*(rq that is not normally used by | |
1396 | software, this fact can be indicated. | |
1397 | If the status line is viewed as an extra line below the bottom line, | |
1398 | then the capability | |
1399 | .B hs | |
1400 | should be given. | |
1401 | Special strings to go to a position in the status line and to return | |
1402 | from the status line can be given as | |
1403 | .B ts | |
1404 | and | |
1405 | .BR fs . | |
1406 | .RB ( fs | |
1407 | must leave the cursor position in the same place that it was before | |
1408 | .BR ts . | |
1409 | If necessary, the | |
1410 | .B sc | |
1411 | and | |
1412 | .B rc | |
1413 | strings can be included in | |
1414 | .B ts | |
1415 | and | |
1416 | .B fs | |
1417 | to get this effect.) | |
1418 | The capability | |
1419 | .B ts | |
1420 | takes one parameter, which is the column number of the status line | |
1421 | to which the cursor is to be moved. | |
1422 | If escape sequences and other special commands such as tab work while in | |
1423 | the status line, the flag | |
1424 | .B es | |
1425 | can be given. | |
1426 | A string that turns off the status line (or otherwise erases its contents) | |
1427 | should be given as | |
1428 | .BR ds . | |
1429 | The status line is normally assumed to be the same width as the | |
1430 | rest of the screen, | |
1431 | .IR i.e. , | |
1432 | .BR co . | |
1433 | If the status line is a different width (possibly because the terminal | |
1434 | does not allow an entire line to be loaded), then its width in columns | |
1435 | can be indicated with the numeric parameter | |
1436 | .BR ws . | |
1437 | .PP | |
1438 | If the terminal can move up or down half a line, this can be | |
1439 | indicated with | |
1440 | .B hu | |
1441 | (half-line up) and | |
1442 | .B hd | |
1443 | (half-line down). | |
1444 | This is primarily useful for superscripts and subscripts on hardcopy | |
1445 | terminals. | |
1446 | If a hardcopy terminal can eject to the next page (form feed), | |
1447 | give this as | |
1448 | .B ff | |
1449 | (usually | |
1450 | .BR ^L ). | |
1451 | .PP | |
1452 | If there is a command to repeat a given character a given number of times | |
1453 | (to save time transmitting a large number of identical characters), | |
1454 | this can be indicated with the parameterized string | |
1455 | .BR rp . | |
1456 | The first parameter is the character to be repeated and the second is | |
1457 | the number of times to repeat it. | |
1458 | (This is a | |
1459 | .I terminfo\^ | |
1460 | feature that is unlikely to be supported by a program that uses | |
1461 | .IR termcap\^ .) | |
1462 | .PP | |
1463 | If the terminal has a settable command character, such as the | |
1464 | Tektronix 4025, this can be indicated with | |
1465 | .BR CC . | |
1466 | A prototype command character is chosen which is used in all capabilities. | |
1467 | This character is given in the | |
1468 | .B CC | |
1469 | capability to identify it. | |
1470 | The following convention is supported on some UNIX systems: | |
1471 | The environment is to be searched for a | |
1472 | .B | |
1473 | .SM CC | |
1474 | variable, | |
1475 | and if found, | |
1476 | all occurrences of the prototype character are replaced by the character | |
1477 | in the environment variable. | |
1478 | This use of the | |
1479 | .B | |
1480 | .SM CC | |
1481 | environment variable | |
1482 | is a very bad idea, as it conflicts with | |
1483 | .IR make\^ (1). | |
1484 | .PP | |
1485 | Terminal descriptions that do not represent a specific kind of known | |
1486 | terminal, such as | |
1487 | .IR switch\^ , | |
1488 | .IR dialup\^ , | |
1489 | .IR patch\^ , | |
1490 | and | |
1491 | .IR network\^ , | |
1492 | should include the | |
1493 | .B gn | |
1494 | (generic) capability so that programs can complain that they do not know | |
1495 | how to talk to the terminal. | |
1496 | (This capability does not apply to | |
1497 | .I virtual\^ | |
1498 | terminal descriptions for which the escape sequences are known.) | |
1499 | .PP | |
1500 | If the terminal uses xoff/xon (\s-2DC3\s0/\s-2DC1\s0) | |
1501 | handshaking for flow control, give | |
1502 | .BR xo . | |
1503 | Padding information should still be included so that routines can make | |
1504 | better decisions about costs, but actual pad characters will not be | |
1505 | transmitted. | |
1506 | .PP | |
1507 | If the terminal has a \*(lqmeta key\*(rq which acts as a shift key, setting the | |
1508 | 8th bit of any character transmitted, then this fact can be indicated with | |
1509 | .BR km . | |
1510 | Otherwise, software will assume that the 8th bit is parity and it will | |
1511 | usually be cleared. | |
1512 | If strings exist to turn this \*(lqmeta mode\*(rq on and off, they can be given as | |
1513 | .B mm | |
1514 | and | |
1515 | .BR mo . | |
1516 | .PP | |
1517 | If the terminal has more lines of memory than will fit on the screen at once, | |
1518 | the number of lines of memory can be indicated with | |
1519 | .BR lm . | |
1520 | An explicit value of 0 indicates that the number of lines is not fixed, | |
1521 | but that there is still more memory than fits on the screen. | |
1522 | .PP | |
1523 | If the terminal is one of those supported by the UNIX system virtual | |
1524 | terminal protocol, the terminal number can be given as | |
1525 | .BR vt . | |
1526 | .PP | |
1527 | Media copy strings which control an auxiliary printer | |
1528 | connected to the terminal can be given as | |
1529 | .BR ps : | |
1530 | print the contents of the screen; | |
1531 | .BR pf : | |
1532 | turn off the printer; and | |
1533 | .BR po : | |
1534 | turn on the printer. | |
1535 | When the printer is on, all text sent to the terminal will be sent to the | |
1536 | printer. | |
1537 | It is undefined whether the text is also displayed on the terminal screen | |
1538 | when the printer is on. | |
1539 | A variation | |
1540 | .B pO | |
1541 | takes one parameter and leaves the printer on for as many characters as the | |
1542 | value of the parameter, then turns the printer off. | |
1543 | The parameter should not exceed 255. | |
1544 | All text, including | |
1545 | .BR pf , | |
1546 | is transparently passed to the printer while | |
1547 | .B pO | |
1548 | is in effect. | |
1549 | .PP | |
1550 | Strings to program function keys can be given as | |
1551 | .BR pk , | |
1552 | .BR pl , | |
1553 | and | |
1554 | .BR px . | |
1555 | Each of these strings takes two parameters: the function key number | |
1556 | to program (from 0 to 9) and the string to program it with. | |
1557 | Function key numbers out of this range may program undefined keys | |
1558 | in a terminal-dependent manner. | |
1559 | The differences among the capabilities are that | |
1560 | .B pk | |
1561 | causes pressing the given key to be the same as the user typing the given | |
1562 | string; | |
1563 | .B pl | |
1564 | causes the string to be executed by the terminal in local mode; | |
1565 | and | |
1566 | .B px | |
1567 | causes the string to be transmitted to the computer. | |
1568 | Unfortunately, due to lack of a definition for string parameters in | |
1569 | .IR termcap\^ , | |
1570 | only | |
1571 | .I terminfo\^ | |
1572 | supports these capabilities. | |
1573 | .br | |
1574 | .ne 5 | |
1575 | .PP | |
1576 | .B Glitches and Braindamage | |
1577 | .PP | |
1578 | Hazeltine terminals, which do not allow `~' characters to be displayed, | |
1579 | should indicate | |
1580 | .BR hz . | |
1581 | .PP | |
1582 | The | |
1583 | .B nc | |
1584 | capability, now obsolete, formerly indicated Datamedia terminals, | |
1585 | which echo | |
1586 | .B \er \en | |
1587 | for | |
1588 | carriage return then ignore a following linefeed. | |
1589 | .PP | |
1590 | Terminals that ignore a linefeed immediately after an | |
1591 | .B am | |
1592 | wrap, such as the Concept, should indicate | |
1593 | .BR xn . | |
1594 | .PP | |
1595 | If | |
1596 | .B ce | |
1597 | is required to get rid of standout | |
1598 | (instead of merely writing normal text on top of it), | |
1599 | .B xs | |
1600 | should be given. | |
1601 | .PP | |
c4737001 | 1602 | Teleray terminals, where tabs turn all characters moved over to blanks, |
ef978bfe JB |
1603 | should indicate |
1604 | .B xt | |
1605 | (destructive tabs). | |
1606 | This glitch is also taken to mean that it is not possible | |
1607 | to position the cursor on top of a \*(lqmagic cookie\*(rq, and that | |
1608 | to erase standout mode it is necessary to use delete and insert line. | |
c4737001 | 1609 | .PP |
ef978bfe JB |
1610 | The Beehive Superbee, which is unable to correctly transmit the |
1611 | \s-2ESC\s0 or ^C characters, has | |
1612 | .BR xb , | |
1613 | indicating that the \*(lqf1\*(rq key is used for \s-2ESC\s0 and \*(lqf2\*(rq for ^C. | |
1614 | (Only certain Superbees have this problem, depending on the ROM.) | |
1615 | .PP | |
1616 | Other specific terminal problems may be corrected by adding more | |
1617 | capabilities of the form \fBx\fIx\^\fP. | |
1618 | .br | |
1619 | .ne 5 | |
c4737001 KM |
1620 | .PP |
1621 | .B Similar Terminals | |
1622 | .PP | |
1623 | If there are two very similar terminals, | |
1624 | one can be defined as being just like the other with certain exceptions. | |
ef978bfe JB |
1625 | The string capability |
1626 | .B tc | |
1627 | can be given | |
c4737001 | 1628 | with the name of the similar terminal. |
ef978bfe JB |
1629 | This capability must be |
1630 | .IR last\^ , | |
1631 | and the combined length of the entries | |
1632 | must not exceed 1024. | |
1633 | The capabilities given before | |
1634 | .B tc | |
1635 | override those in the terminal type invoked by | |
1636 | .BR tc . | |
1637 | A capability can be canceled by placing | |
1638 | .B xx@ | |
1639 | to the left of the | |
1640 | .B tc | |
1641 | invocation, where | |
1642 | .I xx\^ | |
1643 | is the capability. | |
c4737001 KM |
1644 | For example, the entry |
1645 | .PP | |
ef978bfe | 1646 | hn\||\|2621\-nl:ks@:ke@:tc=2621: |
c4737001 | 1647 | .PP |
ef978bfe JB |
1648 | defines a \*(lq2621\-nl\*(rq that does not have the |
1649 | .B ks | |
1650 | or | |
1651 | .B ke | |
1652 | capabilities, | |
1653 | hence does not turn on the function key labels when in visual mode. | |
c4737001 KM |
1654 | This is useful for different modes for a terminal, or for different |
1655 | user preferences. | |
c4737001 KM |
1656 | .SH AUTHOR |
1657 | William Joy | |
1658 | .br | |
1659 | Mark Horton added underlining and keypad support | |
ef978bfe JB |
1660 | .SH FILES |
1661 | .DT | |
1662 | /etc/termcap file containing terminal descriptions | |
1663 | .SH SEE ALSO | |
1e1561a8 JK |
1664 | ex(1), more(1), tset(1), ul(1), vi(1), curses(3X), printf(3S), |
1665 | termcap(3X), term(7) | |
ef978bfe JB |
1666 | .SH "CAVEATS AND BUGS" |
1667 | .B Note: | |
1668 | .I termcap\^ | |
1669 | was replaced by | |
1670 | .I terminfo\^ | |
1671 | in UNIX System V Release 2.0. | |
1672 | The transition will be relatively painless if capabilities flagged as | |
1673 | \*(lqobsolete\*(rq are avoided. | |
1674 | .PP | |
f3531ae0 JB |
1675 | Lines and columns are now stored by the kernel as well as in the termcap |
1676 | entry. | |
1677 | Most programs now use the kernel information primarily; the information | |
1678 | in this file is used only if the kernel does not have any information. | |
1679 | .PP | |
ef978bfe | 1680 | .I Vi\^ |
c4737001 KM |
1681 | allows only 256 characters for string capabilities, and the routines |
1682 | in | |
ef978bfe | 1683 | .IR termlib\^ (3) |
c4737001 KM |
1684 | do not check for overflow of this buffer. |
1685 | The total length of a single entry (excluding only escaped newlines) | |
1686 | may not exceed 1024. | |
1687 | .PP | |
c4737001 | 1688 | Not all programs support all entries. |