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