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