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