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