+.TH TERMCAP UCB 4/8/79 UCB
+.SH NAME
+termcap \- terminal capability data base
+.SH SYNOPSIS
+/etc/termcap
+.SH DESCRIPTION
+.I Termcap
+is a data base describing terminals used primarily by
+.IR ex (UCB)
+and
+.IR vi (UCB),
+and also by
+.IR tset (UCB).
+Terminals are described in
+.I termcap
+by giving a set of capabilities which they have, and by describing
+how operations are performed.
+Padding requirements and initialization sequences
+are included in
+.I termcap.
+.PP
+Entries in
+.I termcap
+consist of a number of `:' separated fields.
+The first entry for each terminal gives the names which are known for the
+terminal, separated by `|' characters. The first name is always 2 characters
+long and is used by older version 6 systems which store the terminal type
+in a 16 bit word in a systemwide data base.
+The second name given is the most common abbreviation for the terminal, and the
+last name given should be a long name fully identifying the terminal.
+The second name should contain no blanks; the last name may well contain
+blanks for readability.
+.PP
+The following entry, which describes the Concept\-100, is among the more
+complex entries in the
+.I termcap
+file as of this writing.
+.PP
+.nf
+c1|c100|concept100:is=\eEU\eEf\eE7\eE5\eE8\eEl\eENH\eEK\eE\e200\eEo&\e200:\e
+ :al=3*\eE^R:am:bs:cd=16*\eE^C:ce=16\eE^S:cl=2*^L:cm=\eEa%+ %+ :co#80:\e
+ :dc=16\eE^A:dl=3*\eE^B:ei=\eE\e200:eo:im=\eE^P:in:ip=16*:li#24:mi:nd=\eE=:\e
+ :se=\eEd\eEe:so=\eED\eEE:ta=8\et:ul:up=\eE;:vb=\eEk\eEK:xn:
+.fi
+.PP
+Note that entries may continue onto multiple lines by giving a \e as the last
+character of a line, and that empty fields
+may be included for readability (here between the last field on a line
+and the first field on the next).
+Capabilities in
+.I termcap
+are of three types:
+Boolean capabilities which indicate that the terminal has
+some particular feature, numeric capabilities giving the size of the terminal
+or the size of particular delays, and string
+capabilities, which give a sequence which can be used to perform particular
+terminal operations.
+.PP
+All capabilities have two letter codes. For instance, the fact that
+the Concept has ``automatic margins'' (i.e. an automatic return and linefeed
+when the end of a line is reached) is indicated by the capability \fBam\fR.
+Hence the description of the Concept includes \fBam\fR.
+Numeric capabilities are followed by the character `#' and then the value.
+Thus \fBco\fR which indicates the number of columns the terminal has
+gives the value `80' for the Concept.
+.PP
+Finally, string valued capabilities, such as \fBce\fR (clear to end of line
+sequence) are given by the two character code, an `=', and then a string
+ending at the next following `:'. A delay in milliseconds may appear after
+the `=' in such a capability, and padding characters are supplied by the
+editor after the remainder of the string is sent to provide this delay.
+The delay can be either a integer, e.g. `20', or an integer followed by
+an `*', i.e. `3*'. A `*' indicates that the padding required is proportional
+to the number of lines affected by the operation, and the amount given is
+the per-affected-unit padding required.
+When a `*' is specified, it is sometimes useful to give a delay of the form
+`3.5' specify a delay per unit to tenths of milliseconds.
+.PP
+A number of escape sequences are provided in the string valued capabilities
+for easy encoding of characters there. A \fB\eE\fR maps to an \s-2ESCAPE\s0
+character, \fB^x\fR maps to a control-x, and the sequences
+\fB\en \er \et \eb \ef\fR give a newline, return, tab, backspace and formfeed.
+Finally, characters may be given as three octal digits after a \fB\e\fR,
+and the characters \fB^\fR and \fB\fR may be given as \fB\e^\fR and \fB\e\e\fR.
+If it is necessary to place a \fB:\fR in a capability it must be escaped in
+octal as \fB\e072\fR.
+If it is necessary to place a null character in a string capability it
+must be encoded as \fB\e200\fR. The routines which deal with
+.I termcap
+use C strings, and strip the high bits of the output very late so that
+a \fB\e200\fR comes out as a \fB\e000\fR would.
+.PP
+We now outline how to prepare descriptions of terminals.
+The most effective way to prepare a terminal description is by imitating
+the description of a similar terminal in
+.I termcap
+and to build up a description gradually, using partial descriptions
+with
+.I ex
+to check that they are correct.
+Be aware that a very unusual terminal may expose deficiencies in
+the ability of the
+.I termcap
+file to describe it
+or bugs in
+.I ex.
+To easily test a new terminal description you can set the environment variable
+TERMCAP to a pathname of a file containing the description you are working
+on and the editor will look there rather than in
+.I /etc/termcap.
+(This only works on version 7 systems.)
+.PP
+.B Basic capabilities
+.PP
+The number of columns on each line for the terminal is given by the
+\fBco\fR numeric capability. If the terminal is a \s-2CRT\s0, then the
+number of lines on the screen is given by the \fBli\fR capability.
+If the terminal wraps around to the beginning of the next line when
+it reaches the right margin, then it should have the \fBam\fR capability.
+If the terminal can clear its screen, then this is given by the
+\fBcl\fR string capability. If the terminal can backspace, then it
+should have the \fBbs\fR capability, unless a backspace is accomplished
+by a character other than \fB^H\fR (ugh) in which case you should give
+this character as the \fBbc\fR string capability. If it overstrikes
+(rather than clearing a position when a character is struck over)
+then it should have the \fBos\fR capability.
+.PP
+A very important point here is that the local cursor motions encoded
+in
+.I termcap
+are undefined at the left and top edges of a \s-2CRT\s0 terminal.
+The editor will never attempt to backspace around the left edge, nor
+will it attempt to go up locally off the top. The editor assumes that
+feeding off the bottom of the screen will cause the screen to scroll up,
+and the \fBam\fR capability tells whether the cursor sticks at the right
+edge of the screen. If the terminal has switch selectable automatic margins,
+the
+.I termcap
+file always assumes that this is on, i.e. \fBam\fR.
+.PP
+These capabilities suffice to describe hardcopy and ``glass-tty'' terminals.
+Thus the model 33 teletype is described as
+.PP
+.DT
+ t3|33|tty33:co#72:os
+.PP
+while the Lear Siegler \s-2ADM\-3\s0 is described as
+.PP
+.DT
+ cl|adm3|3|lsi adm3:am:bs:cl=^Z:li#24:co#80
+.PP
+.B Cursor addressing
+.PP
+Cursor addressing in the terminal is described by a
+\fBcm\fR string capability, with
+.IR printf (3s)
+like escapes \fB%x\fR in it.
+These substitute to encodings of the current line or column position,
+while other characters are passed through unchanged.
+If the \fBcm\fR string is thought of as being a function, then its
+arguments are the line and then the column to which motion is desired,
+and the \fB%\fR encodings have the following meanings:
+.PP
+.DT
+.nf
+ %d as in \fIprintf\fR, 0 origin
+ %2 like %2d
+ %3 like %3d
+ %. like %c
+ %+x adds \fIx\fR to value, then %.
+ %<xy if value < x adds y; then in any case %.
+ %r reverses order of line and column, no output
+ %i increments line/column (for 1 origin)
+ %% gives a single %
+ %n exclusive or row and column with 0140 (DM2500)
+.fi
+.PP
+Consider the HP2645, which, to get to row 3 and column 12, needs
+to be sent \eE&a12c03Y padded for 6 milliseconds. Note that the order
+of the rows and columns is inverted here, and that the row and column
+are printed as two digits. Thus its \fBcm\fR capability is ``cm=6\eE&%r%2c%2Y''.
+The Microterm \s-2ACT-IV\s0 needs the current row and column sent
+preceded by a \fB^T\fR, with the row and column simply encoded in binary,
+``cm=^T%.%.''. Terminals which use ``%.'' need to be able to
+backspace the cursor (\fBbs\fR or \fBbc\fR),
+and to move the cursor up one line on the screen (\fBup\fR introduced below).
+This is necessary because it is not always safe to transmit \fB\et\fR, \fB\en\fR
+\fB^D\fR and \fB\er\fR, as the system may change or discard them.
+.PP
+A final example is the \s-2LSI ADM-3a\s0, which uses row and column
+offset by a blank character, thus ``cm=\eE=%+ %+ ''.
+.PP
+.B Cursor motions
+.PP
+If the terminal can move the cursor one position to the right, leaving
+the character at the current position unchanged, then this sequence should
+be given as \fBnd\fR (non-destructive space). If it can move the cursor
+up a line
+on the screen in the same column, this should be given as \fBup\fR.
+If the terminal has no cursor addressing capability, but can home the cursor
+cursor (to very upper left corner of screen) then this can be given as
+\fBho\fR; similarly a fast way of getting to the lower left hand corner
+can be given as \fBll\fR; this may involve going up with \fBup\fR
+from the home position,
+but the editor will never do this itself (unless \fBll\fR does) because it
+makes no assumption about the effect of moving up from the home position.
+.PP
+.B Area clears
+.PP
+If the terminal can clear from the current position to the end of the
+line, leaving the cursor where it is, this should be given as \fBce\fR.
+If the terminal can clear from the current position to the end of the
+display, then this should be given as \fBcd\fR.
+The editor only uses
+\fBcd\fR from the first column of a line.
+.PP
+.B Insert/delete line
+.PP
+If the terminal can open a new blank line before the line where the cursor
+is, this should be given as \fBal\fR; this is done only from the first
+position of a line. The cursor must then appear on the newly blank line.
+If the terminal can delete the line which the cursor is on, then this
+should be given as \fBdl\fR; this is done only from the first position on
+the line to be deleted.
+If the terminal can scroll the screen backwards, then this can be given as
+\fBsb\fR, but just \fBal\fR suffices.
+If the terminal can retain display memory above then the
+\fBda\fR capability should be given; if display memory can be retained
+below then \fBdb\fR should be given. These let the editor understand
+that deleting a line on the screen may bring non-blank lines up from below
+or that scrolling back with \fBsb\fR may bring down non-blank lines.
+.PP
+.B Insert/delete character
+.PP
+There are two basic kinds of intelligent terminals with respect to
+insert/delete character which can be described using
+.I termcap.
+The most common insert/delete character operations affect only the characters
+on the current line and shift characters off the end of the line rigidly.
+Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make
+a distinction between typed and untyped blanks on the screen, shifting
+upon an insert or delete only to an untyped blank on the screen which is
+either eliminated, or expanded to two untyped blanks. You can find out
+which kind of terminal you have by clearing the screen and then typing
+text separated by cursor motions. Type ``abc\ \ \ \ def'' using local
+cursor motions (not spaces) between the ``abc'' and the ``def''.
+Then position the cursor before the ``abc'' and put the terminal in insert
+mode. If typing characters causes the rest of the line to shift
+rigidly and characters to fall off the end, then your terminal does
+not distinguish between blanks and untyped positions. If the ``abc''
+shifts over to the ``def'' which then move together around the end of the
+current line and onto the next as you insert, you have the second type of
+terminal, and should give the capability \fBin\fR, which stands for
+``insert null''. If your terminal does something different and unusual
+then you may have to modify the editor to get it to use the insert
+mode your terminal defines. We have seen no terminals which have an insert
+mode not not falling into one of these two classes.
+.PP
+The editor can handle both terminals which have an insert mode, and terminals
+which send a simple sequence to open a blank position on the current line.
+Give as \fBim\fR the sequence to get into insert mode, or give it an
+empty value if your terminal uses a sequence to insert a blank position.
+Give as \fBei\fR the sequence to leave insert mode (give this, with
+an empty value also if you gave \fBim\fR so).
+Now give as \fBic\fR any sequence needed to be sent just before sending
+the character to be inserted. Most terminals with a true insert mode
+will not give \fBic\fR, terminals which send a sequence to open a screen
+position should give it here. (Insert mode is preferable to the sequence
+to open a position on the screen if your terminal has both.)
+If post insert padding is needed, give this as a number of milliseconds
+in \fBip\fR (a string option). Any other sequence which may need to be
+sent after an insert of a single character may also be given in \fBip\fR.
+.PP
+It is occasionally necessary to move around while in insert mode
+to delete characters on the same line (e.g. if there is a tab after
+the insertion position). If your terminal allows motion while in
+insert mode you can give the capability \fBmi\fR to speed up inserting
+in this case. Omitting \fBmi\fR will affect only speed. Some terminals
+(notably Datamedia's) must not have \fBmi\fR because of the way their
+insert mode works.
+.PP
+Finally, you can specify delete mode by giving \fBdm\fR and \fBed\fR
+to enter and exit delete mode, and \fBdc\fR to delete a single character
+while in delete mode.
+.PP
+.B Highlighting and visible bells
+.PP
+If your terminal has sequences to enter and exit standout mode these
+can be given as \fBso\fR and \fBse\fR respectively. If the terminal has
+a way of flashing the screen to indicate an error quietly (a bell replacement)
+then this can be given as \fBvb\fR; it must not move the cursor.
+Finally, if the terminal should be placed in a different mode during
+open and visual modes of
+.I ex,
+this can be given as
+\fBvs\fR and \fBve\fR, sent at the start and end of these modes
+respectively. These can be used to change, e.g., from a underline
+to a block cursor and back.
+.PP
+.B Miscellaneous
+.PP
+If your terminal correctly generates underlined characters (with no
+special codes needed) even though the
+it does not overstrike, then you should give the capability \fBul\fR;
+If overstrikes are erasable with a blank, then this should be indicated
+by giving \fBeo\fR.
+.PP
+If the terminal requires other than a null (zero) character as a pad,
+then this can be given as \fBpc\fR.
+.PP
+If it has cursor motion keys
+which generate single control characters, then the \fBma\fR option
+can be set up to map these to the normal editor functions;
+the map ``ma=^K^P'' maps a control-K, which moves the cursor up one line
+on an \s-2ADM-3A\s0, to a control-P, which is the editor function to
+move the cursor up one line. Many pairs of characters may be given to
+\fBma\fR.
+.PP
+If tabs on the terminal require padding, or if the terminal uses a
+character other than \fB^I\fR to tab, then this can be given as \fBta\fR.
+.PP
+Hazeltine terminals, which don't allow `~' characters to be printed should
+indicate \fBhz\fR.
+Datamedia terminals, which echo carriage-return newline for carriage return
+and then ignore a following newline should indicate \fBnc\fR.
+Early Concept terminals, which ignore a newline immediately after an \fBam\fR
+wrap, should indicate \fBxn\fR.
+Other specific terminal problems may be corrected by adding more
+capabilities of the form \fBx\fIx\fR.
+.PP
+Other capabilities utilized only by
+.I tset (UCB)
+include \fBis\fR, an initialization string for the terminal,
+and \fBif\fR, the name of a file containing long initialization strings.
+.SH FILES
+.DT
+/etc/termcap file containing terminal descriptions
+.SH SEE ALSO
+ex (UCB), termlib (UCB), tset (UCB), vi (UCB)
+.SH AUTHOR
+William Joy
+.SH BUGS
+.I Ex
+allows only 128 characters for string capabilities, and the routines
+in
+.I termlib
+do not check for overflow of this buffer.
+.SH CAPABILITIES
+.nf
+(P) indicates padding may be specified
+(P*) indicates that padding may be based on no. lines affected
+
+.ta .7i 1.4i 2.1i
+\fBName Type Pad? Description\fR
+al str (P*) Add new blank line
+am bool Terminal has automatic margins
+bc str Back cursor if not \fB^H\fR
+bs bool Terminal can backspace with \fB^H\fR
+cd str (P*) Clear to end of display
+co num Number of columns in a line
+ce str (P) Clear to end of line
+cl str (P*) Clear screen
+cm str (P) Cursor motion
+da bool Display may be retained above
+db bool Display may be retained below
+dc str (P*) Delete character
+dl str (P*) Delete line
+dm str Delete mode (enter)
+ed str End delete mode
+ei str End insert mode; give ``:ei=:'' if \fBic\fR
+eo str Can erase overstrikes with a blank
+ho str Home cursor (if no \fBcm\fR)
+hz str Hazeltine; can't print ~'s
+ic str (P) Insert character
+if \- Name of file containing \fBis\fR
+im bool Insert mode (enter); give ``:im=:'' if \fBic\fR
+in bool Insert mode distinguishes nulls on display
+ip str (P*) Insert pad after character inserted
+is str Terminal initialization string
+li num Number of lines on \s-2CRT\s0 screen
+ll str Last line, first column (if no \fBcm\fR)
+ma str Control character map for arrow keys
+mi bool Safe to move while in insert mode
+nc bool No correctly working carriage return (DM2500)
+nd str Non-destructive space (cursor right)
+os bool Terminal overstrikes
+pc str Pad character (rather than null)
+se str End stand out mode
+sf str (P) Scroll forwards
+so str Begin stand out mode
+sr str (P) Scroll reverse (backwards)
+ta str (P) Tab (other than ^I or with padding)
+ul bool Terminal underlines even though it doesn't overstrike
+up str Upline (cursor up)
+vb str Visible bell (may not move cursor)
+ve str Sequence to end open/visual mode
+vs str Sequence to start open/visual mode
+xn str A newline is ignored after a wrap (Concept)
projects / unix-history / commitdiff