| 1 | .TH TERMCAP UCB 4/8/79 UCB |
| 2 | .SH NAME |
| 3 | termcap \- terminal capability data base |
| 4 | .SH SYNOPSIS |
| 5 | /etc/termcap |
| 6 | .SH DESCRIPTION |
| 7 | .I Termcap |
| 8 | is a data base describing terminals used primarily by |
| 9 | .IR ex (UCB) |
| 10 | and |
| 11 | .IR vi (UCB), |
| 12 | and also by |
| 13 | .IR tset (UCB). |
| 14 | Terminals are described in |
| 15 | .I termcap |
| 16 | by giving a set of capabilities which they have, and by describing |
| 17 | how operations are performed. |
| 18 | Padding requirements and initialization sequences |
| 19 | are included in |
| 20 | .I termcap. |
| 21 | .PP |
| 22 | Entries in |
| 23 | .I termcap |
| 24 | consist of a number of `:' separated fields. |
| 25 | The first entry for each terminal gives the names which are known for the |
| 26 | terminal, separated by `|' characters. The first name is always 2 characters |
| 27 | long and is used by older version 6 systems which store the terminal type |
| 28 | in a 16 bit word in a systemwide data base. |
| 29 | The second name given is the most common abbreviation for the terminal, and the |
| 30 | last name given should be a long name fully identifying the terminal. |
| 31 | The second name should contain no blanks; the last name may well contain |
| 32 | blanks for readability. |
| 33 | .PP |
| 34 | The following entry, which describes the Concept\-100, is among the more |
| 35 | complex entries in the |
| 36 | .I termcap |
| 37 | file as of this writing. |
| 38 | .PP |
| 39 | .nf |
| 40 | c1|c100|concept100:is=\eEU\eEf\eE7\eE5\eE8\eEl\eENH\eEK\eE\e200\eEo&\e200:\e |
| 41 | :al=3*\eE^R:am:bs:cd=16*\eE^C:ce=16\eE^S:cl=2*^L:cm=\eEa%+ %+ :co#80:\e |
| 42 | :dc=16\eE^A:dl=3*\eE^B:ei=\eE\e200:eo:im=\eE^P:in:ip=16*:li#24:mi:nd=\eE=:\e |
| 43 | :se=\eEd\eEe:so=\eED\eEE:ta=8\et:ul:up=\eE;:vb=\eEk\eEK:xn: |
| 44 | .fi |
| 45 | .PP |
| 46 | Note that entries may continue onto multiple lines by giving a \e as the last |
| 47 | character of a line, and that empty fields |
| 48 | may be included for readability (here between the last field on a line |
| 49 | and the first field on the next). |
| 50 | Capabilities in |
| 51 | .I termcap |
| 52 | are of three types: |
| 53 | Boolean capabilities which indicate that the terminal has |
| 54 | some particular feature, numeric capabilities giving the size of the terminal |
| 55 | or the size of particular delays, and string |
| 56 | capabilities, which give a sequence which can be used to perform particular |
| 57 | terminal operations. |
| 58 | .PP |
| 59 | All capabilities have two letter codes. For instance, the fact that |
| 60 | the Concept has ``automatic margins'' (i.e. an automatic return and linefeed |
| 61 | when the end of a line is reached) is indicated by the capability \fBam\fR. |
| 62 | Hence the description of the Concept includes \fBam\fR. |
| 63 | Numeric capabilities are followed by the character `#' and then the value. |
| 64 | Thus \fBco\fR which indicates the number of columns the terminal has |
| 65 | gives the value `80' for the Concept. |
| 66 | .PP |
| 67 | Finally, string valued capabilities, such as \fBce\fR (clear to end of line |
| 68 | sequence) are given by the two character code, an `=', and then a string |
| 69 | ending at the next following `:'. A delay in milliseconds may appear after |
| 70 | the `=' in such a capability, and padding characters are supplied by the |
| 71 | editor after the remainder of the string is sent to provide this delay. |
| 72 | The delay can be either a integer, e.g. `20', or an integer followed by |
| 73 | an `*', i.e. `3*'. A `*' indicates that the padding required is proportional |
| 74 | to the number of lines affected by the operation, and the amount given is |
| 75 | the per-affected-unit padding required. |
| 76 | When a `*' is specified, it is sometimes useful to give a delay of the form |
| 77 | `3.5' specify a delay per unit to tenths of milliseconds. |
| 78 | .PP |
| 79 | A number of escape sequences are provided in the string valued capabilities |
| 80 | for easy encoding of characters there. A \fB\eE\fR maps to an \s-2ESCAPE\s0 |
| 81 | character, \fB^x\fR maps to a control-x, and the sequences |
| 82 | \fB\en \er \et \eb \ef\fR give a newline, return, tab, backspace and formfeed. |
| 83 | Finally, characters may be given as three octal digits after a \fB\e\fR, |
| 84 | and the characters \fB^\fR and \fB\fR may be given as \fB\e^\fR and \fB\e\e\fR. |
| 85 | If it is necessary to place a \fB:\fR in a capability it must be escaped in |
| 86 | octal as \fB\e072\fR. |
| 87 | If it is necessary to place a null character in a string capability it |
| 88 | must be encoded as \fB\e200\fR. The routines which deal with |
| 89 | .I termcap |
| 90 | use C strings, and strip the high bits of the output very late so that |
| 91 | a \fB\e200\fR comes out as a \fB\e000\fR would. |
| 92 | .PP |
| 93 | We now outline how to prepare descriptions of terminals. |
| 94 | The most effective way to prepare a terminal description is by imitating |
| 95 | the description of a similar terminal in |
| 96 | .I termcap |
| 97 | and to build up a description gradually, using partial descriptions |
| 98 | with |
| 99 | .I ex |
| 100 | to check that they are correct. |
| 101 | Be aware that a very unusual terminal may expose deficiencies in |
| 102 | the ability of the |
| 103 | .I termcap |
| 104 | file to describe it |
| 105 | or bugs in |
| 106 | .I ex. |
| 107 | To easily test a new terminal description you can set the environment variable |
| 108 | TERMCAP to a pathname of a file containing the description you are working |
| 109 | on and the editor will look there rather than in |
| 110 | .I /etc/termcap. |
| 111 | (This only works on version 7 systems.) |
| 112 | .PP |
| 113 | .B Basic capabilities |
| 114 | .PP |
| 115 | The number of columns on each line for the terminal is given by the |
| 116 | \fBco\fR numeric capability. If the terminal is a \s-2CRT\s0, then the |
| 117 | number of lines on the screen is given by the \fBli\fR capability. |
| 118 | If the terminal wraps around to the beginning of the next line when |
| 119 | it reaches the right margin, then it should have the \fBam\fR capability. |
| 120 | If the terminal can clear its screen, then this is given by the |
| 121 | \fBcl\fR string capability. If the terminal can backspace, then it |
| 122 | should have the \fBbs\fR capability, unless a backspace is accomplished |
| 123 | by a character other than \fB^H\fR (ugh) in which case you should give |
| 124 | this character as the \fBbc\fR string capability. If it overstrikes |
| 125 | (rather than clearing a position when a character is struck over) |
| 126 | then it should have the \fBos\fR capability. |
| 127 | .PP |
| 128 | A very important point here is that the local cursor motions encoded |
| 129 | in |
| 130 | .I termcap |
| 131 | are undefined at the left and top edges of a \s-2CRT\s0 terminal. |
| 132 | The editor will never attempt to backspace around the left edge, nor |
| 133 | will it attempt to go up locally off the top. The editor assumes that |
| 134 | feeding off the bottom of the screen will cause the screen to scroll up, |
| 135 | and the \fBam\fR capability tells whether the cursor sticks at the right |
| 136 | edge of the screen. If the terminal has switch selectable automatic margins, |
| 137 | the |
| 138 | .I termcap |
| 139 | file always assumes that this is on, i.e. \fBam\fR. |
| 140 | .PP |
| 141 | These capabilities suffice to describe hardcopy and ``glass-tty'' terminals. |
| 142 | Thus the model 33 teletype is described as |
| 143 | .PP |
| 144 | .DT |
| 145 | t3|33|tty33:co#72:os |
| 146 | .PP |
| 147 | while the Lear Siegler \s-2ADM\-3\s0 is described as |
| 148 | .PP |
| 149 | .DT |
| 150 | cl|adm3|3|lsi adm3:am:bs:cl=^Z:li#24:co#80 |
| 151 | .PP |
| 152 | .B Cursor addressing |
| 153 | .PP |
| 154 | Cursor addressing in the terminal is described by a |
| 155 | \fBcm\fR string capability, with |
| 156 | .IR printf (3s) |
| 157 | like escapes \fB%x\fR in it. |
| 158 | These substitute to encodings of the current line or column position, |
| 159 | while other characters are passed through unchanged. |
| 160 | If the \fBcm\fR string is thought of as being a function, then its |
| 161 | arguments are the line and then the column to which motion is desired, |
| 162 | and the \fB%\fR encodings have the following meanings: |
| 163 | .PP |
| 164 | .DT |
| 165 | .nf |
| 166 | %d as in \fIprintf\fR, 0 origin |
| 167 | %2 like %2d |
| 168 | %3 like %3d |
| 169 | %. like %c |
| 170 | %+x adds \fIx\fR to value, then %. |
| 171 | %<xy if value < x adds y; then in any case %. |
| 172 | %r reverses order of line and column, no output |
| 173 | %i increments line/column (for 1 origin) |
| 174 | %% gives a single % |
| 175 | %n exclusive or row and column with 0140 (DM2500) |
| 176 | .fi |
| 177 | .PP |
| 178 | Consider the HP2645, which, to get to row 3 and column 12, needs |
| 179 | to be sent \eE&a12c03Y padded for 6 milliseconds. Note that the order |
| 180 | of the rows and columns is inverted here, and that the row and column |
| 181 | are printed as two digits. Thus its \fBcm\fR capability is ``cm=6\eE&%r%2c%2Y''. |
| 182 | The Microterm \s-2ACT-IV\s0 needs the current row and column sent |
| 183 | preceded by a \fB^T\fR, with the row and column simply encoded in binary, |
| 184 | ``cm=^T%.%.''. Terminals which use ``%.'' need to be able to |
| 185 | backspace the cursor (\fBbs\fR or \fBbc\fR), |
| 186 | and to move the cursor up one line on the screen (\fBup\fR introduced below). |
| 187 | This is necessary because it is not always safe to transmit \fB\et\fR, \fB\en\fR |
| 188 | \fB^D\fR and \fB\er\fR, as the system may change or discard them. |
| 189 | .PP |
| 190 | A final example is the \s-2LSI ADM-3a\s0, which uses row and column |
| 191 | offset by a blank character, thus ``cm=\eE=%+ %+ ''. |
| 192 | .PP |
| 193 | .B Cursor motions |
| 194 | .PP |
| 195 | If the terminal can move the cursor one position to the right, leaving |
| 196 | the character at the current position unchanged, then this sequence should |
| 197 | be given as \fBnd\fR (non-destructive space). If it can move the cursor |
| 198 | up a line |
| 199 | on the screen in the same column, this should be given as \fBup\fR. |
| 200 | If the terminal has no cursor addressing capability, but can home the cursor |
| 201 | cursor (to very upper left corner of screen) then this can be given as |
| 202 | \fBho\fR; similarly a fast way of getting to the lower left hand corner |
| 203 | can be given as \fBll\fR; this may involve going up with \fBup\fR |
| 204 | from the home position, |
| 205 | but the editor will never do this itself (unless \fBll\fR does) because it |
| 206 | makes no assumption about the effect of moving up from the home position. |
| 207 | .PP |
| 208 | .B Area clears |
| 209 | .PP |
| 210 | If the terminal can clear from the current position to the end of the |
| 211 | line, leaving the cursor where it is, this should be given as \fBce\fR. |
| 212 | If the terminal can clear from the current position to the end of the |
| 213 | display, then this should be given as \fBcd\fR. |
| 214 | The editor only uses |
| 215 | \fBcd\fR from the first column of a line. |
| 216 | .PP |
| 217 | .B Insert/delete line |
| 218 | .PP |
| 219 | If the terminal can open a new blank line before the line where the cursor |
| 220 | is, this should be given as \fBal\fR; this is done only from the first |
| 221 | position of a line. The cursor must then appear on the newly blank line. |
| 222 | If the terminal can delete the line which the cursor is on, then this |
| 223 | should be given as \fBdl\fR; this is done only from the first position on |
| 224 | the line to be deleted. |
| 225 | If the terminal can scroll the screen backwards, then this can be given as |
| 226 | \fBsb\fR, but just \fBal\fR suffices. |
| 227 | If the terminal can retain display memory above then the |
| 228 | \fBda\fR capability should be given; if display memory can be retained |
| 229 | below then \fBdb\fR should be given. These let the editor understand |
| 230 | that deleting a line on the screen may bring non-blank lines up from below |
| 231 | or that scrolling back with \fBsb\fR may bring down non-blank lines. |
| 232 | .PP |
| 233 | .B Insert/delete character |
| 234 | .PP |
| 235 | There are two basic kinds of intelligent terminals with respect to |
| 236 | insert/delete character which can be described using |
| 237 | .I termcap. |
| 238 | The most common insert/delete character operations affect only the characters |
| 239 | on the current line and shift characters off the end of the line rigidly. |
| 240 | Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make |
| 241 | a distinction between typed and untyped blanks on the screen, shifting |
| 242 | upon an insert or delete only to an untyped blank on the screen which is |
| 243 | either eliminated, or expanded to two untyped blanks. You can find out |
| 244 | which kind of terminal you have by clearing the screen and then typing |
| 245 | text separated by cursor motions. Type ``abc\ \ \ \ def'' using local |
| 246 | cursor motions (not spaces) between the ``abc'' and the ``def''. |
| 247 | Then position the cursor before the ``abc'' and put the terminal in insert |
| 248 | mode. If typing characters causes the rest of the line to shift |
| 249 | rigidly and characters to fall off the end, then your terminal does |
| 250 | not distinguish between blanks and untyped positions. If the ``abc'' |
| 251 | shifts over to the ``def'' which then move together around the end of the |
| 252 | current line and onto the next as you insert, you have the second type of |
| 253 | terminal, and should give the capability \fBin\fR, which stands for |
| 254 | ``insert null''. If your terminal does something different and unusual |
| 255 | then you may have to modify the editor to get it to use the insert |
| 256 | mode your terminal defines. We have seen no terminals which have an insert |
| 257 | mode not not falling into one of these two classes. |
| 258 | .PP |
| 259 | The editor can handle both terminals which have an insert mode, and terminals |
| 260 | which send a simple sequence to open a blank position on the current line. |
| 261 | Give as \fBim\fR the sequence to get into insert mode, or give it an |
| 262 | empty value if your terminal uses a sequence to insert a blank position. |
| 263 | Give as \fBei\fR the sequence to leave insert mode (give this, with |
| 264 | an empty value also if you gave \fBim\fR so). |
| 265 | Now give as \fBic\fR any sequence needed to be sent just before sending |
| 266 | the character to be inserted. Most terminals with a true insert mode |
| 267 | will not give \fBic\fR, terminals which send a sequence to open a screen |
| 268 | position should give it here. (Insert mode is preferable to the sequence |
| 269 | to open a position on the screen if your terminal has both.) |
| 270 | If post insert padding is needed, give this as a number of milliseconds |
| 271 | in \fBip\fR (a string option). Any other sequence which may need to be |
| 272 | sent after an insert of a single character may also be given in \fBip\fR. |
| 273 | .PP |
| 274 | It is occasionally necessary to move around while in insert mode |
| 275 | to delete characters on the same line (e.g. if there is a tab after |
| 276 | the insertion position). If your terminal allows motion while in |
| 277 | insert mode you can give the capability \fBmi\fR to speed up inserting |
| 278 | in this case. Omitting \fBmi\fR will affect only speed. Some terminals |
| 279 | (notably Datamedia's) must not have \fBmi\fR because of the way their |
| 280 | insert mode works. |
| 281 | .PP |
| 282 | Finally, you can specify delete mode by giving \fBdm\fR and \fBed\fR |
| 283 | to enter and exit delete mode, and \fBdc\fR to delete a single character |
| 284 | while in delete mode. |
| 285 | .PP |
| 286 | .B Highlighting and visible bells |
| 287 | .PP |
| 288 | If your terminal has sequences to enter and exit standout mode these |
| 289 | can be given as \fBso\fR and \fBse\fR respectively. If the terminal has |
| 290 | a way of flashing the screen to indicate an error quietly (a bell replacement) |
| 291 | then this can be given as \fBvb\fR; it must not move the cursor. |
| 292 | Finally, if the terminal should be placed in a different mode during |
| 293 | open and visual modes of |
| 294 | .I ex, |
| 295 | this can be given as |
| 296 | \fBvs\fR and \fBve\fR, sent at the start and end of these modes |
| 297 | respectively. These can be used to change, e.g., from a underline |
| 298 | to a block cursor and back. |
| 299 | .PP |
| 300 | .B Miscellaneous |
| 301 | .PP |
| 302 | If your terminal correctly generates underlined characters (with no |
| 303 | special codes needed) even though the |
| 304 | it does not overstrike, then you should give the capability \fBul\fR; |
| 305 | If overstrikes are erasable with a blank, then this should be indicated |
| 306 | by giving \fBeo\fR. |
| 307 | .PP |
| 308 | If the terminal requires other than a null (zero) character as a pad, |
| 309 | then this can be given as \fBpc\fR. |
| 310 | .PP |
| 311 | If it has cursor motion keys |
| 312 | which generate single control characters, then the \fBma\fR option |
| 313 | can be set up to map these to the normal editor functions; |
| 314 | the map ``ma=^K^P'' maps a control-K, which moves the cursor up one line |
| 315 | on an \s-2ADM-3A\s0, to a control-P, which is the editor function to |
| 316 | move the cursor up one line. Many pairs of characters may be given to |
| 317 | \fBma\fR. |
| 318 | .PP |
| 319 | If tabs on the terminal require padding, or if the terminal uses a |
| 320 | character other than \fB^I\fR to tab, then this can be given as \fBta\fR. |
| 321 | .PP |
| 322 | Hazeltine terminals, which don't allow `~' characters to be printed should |
| 323 | indicate \fBhz\fR. |
| 324 | Datamedia terminals, which echo carriage-return newline for carriage return |
| 325 | and then ignore a following newline should indicate \fBnc\fR. |
| 326 | Early Concept terminals, which ignore a newline immediately after an \fBam\fR |
| 327 | wrap, should indicate \fBxn\fR. |
| 328 | Other specific terminal problems may be corrected by adding more |
| 329 | capabilities of the form \fBx\fIx\fR. |
| 330 | .PP |
| 331 | Other capabilities utilized only by |
| 332 | .I tset (UCB) |
| 333 | include \fBis\fR, an initialization string for the terminal, |
| 334 | and \fBif\fR, the name of a file containing long initialization strings. |
| 335 | .SH FILES |
| 336 | .DT |
| 337 | /etc/termcap file containing terminal descriptions |
| 338 | .SH SEE ALSO |
| 339 | ex (UCB), termlib (UCB), tset (UCB), vi (UCB) |
| 340 | .SH AUTHOR |
| 341 | William Joy |
| 342 | .SH BUGS |
| 343 | .I Ex |
| 344 | allows only 128 characters for string capabilities, and the routines |
| 345 | in |
| 346 | .I termlib |
| 347 | do not check for overflow of this buffer. |
| 348 | .SH CAPABILITIES |
| 349 | .nf |
| 350 | (P) indicates padding may be specified |
| 351 | (P*) indicates that padding may be based on no. lines affected |
| 352 | |
| 353 | .ta .7i 1.4i 2.1i |
| 354 | \fBName Type Pad? Description\fR |
| 355 | al str (P*) Add new blank line |
| 356 | am bool Terminal has automatic margins |
| 357 | bc str Back cursor if not \fB^H\fR |
| 358 | bs bool Terminal can backspace with \fB^H\fR |
| 359 | cd str (P*) Clear to end of display |
| 360 | co num Number of columns in a line |
| 361 | ce str (P) Clear to end of line |
| 362 | cl str (P*) Clear screen |
| 363 | cm str (P) Cursor motion |
| 364 | da bool Display may be retained above |
| 365 | db bool Display may be retained below |
| 366 | dc str (P*) Delete character |
| 367 | dl str (P*) Delete line |
| 368 | dm str Delete mode (enter) |
| 369 | ed str End delete mode |
| 370 | ei str End insert mode; give ``:ei=:'' if \fBic\fR |
| 371 | eo str Can erase overstrikes with a blank |
| 372 | ho str Home cursor (if no \fBcm\fR) |
| 373 | hz str Hazeltine; can't print ~'s |
| 374 | ic str (P) Insert character |
| 375 | if \- Name of file containing \fBis\fR |
| 376 | im bool Insert mode (enter); give ``:im=:'' if \fBic\fR |
| 377 | in bool Insert mode distinguishes nulls on display |
| 378 | ip str (P*) Insert pad after character inserted |
| 379 | is str Terminal initialization string |
| 380 | li num Number of lines on \s-2CRT\s0 screen |
| 381 | ll str Last line, first column (if no \fBcm\fR) |
| 382 | ma str Control character map for arrow keys |
| 383 | mi bool Safe to move while in insert mode |
| 384 | nc bool No correctly working carriage return (DM2500) |
| 385 | nd str Non-destructive space (cursor right) |
| 386 | os bool Terminal overstrikes |
| 387 | pc str Pad character (rather than null) |
| 388 | se str End stand out mode |
| 389 | sf str (P) Scroll forwards |
| 390 | so str Begin stand out mode |
| 391 | sr str (P) Scroll reverse (backwards) |
| 392 | ta str (P) Tab (other than ^I or with padding) |
| 393 | ul bool Terminal underlines even though it doesn't overstrike |
| 394 | up str Upline (cursor up) |
| 395 | vb str Visible bell (may not move cursor) |
| 396 | ve str Sequence to end open/visual mode |
| 397 | vs str Sequence to start open/visual mode |
| 398 | xn str A newline is ignored after a wrap (Concept) |