2. The Format of the Data Base

The termcap data base of terminal descriptions is stored in the file ‘/etc/termcap’. It contains terminal descriptions, blank lines, and comments.

A terminal description starts with one or more names for the terminal type. The information in the description is a series of capability names and values. The capability names have standard meanings (see section Definitions of the Terminal Capabilities) and their values describe the terminal.

2.1 Terminal Description Format

Aside from comments (lines starting with ‘#’, which are ignored), each nonblank line in the termcap data base is a terminal description. A terminal description is nominally a single line, but it can be split into multiple lines by inserting the two characters ‘\ newline’. This sequence is ignored wherever it appears in a description.

The preferred way to split the description is between capabilities: insert the four characters ‘: \ newline tab’ immediately before any colon. This allows each sub-line to start with some indentation. This works because, after the ‘\ newline’ are ignored, the result is ‘: tab :’; the first colon ends the preceding capability and the second colon starts the next capability. If you split with ‘\ newline’ alone, you may not add any indentation after them.

Here is a real example of a terminal description:

dw|vt52|DEC vt52:\
        :cr=^M:do=^J:nl=^J:bl=^G:\
        :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
        :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:

Each terminal description begins with several names for the terminal type. The names are separated by ‘|’ characters, and a colon ends the last name. The first name should be two characters long; it exists only for the sake of very old Unix systems and is never used in modern systems. The last name should be a fully verbose name such as “DEC vt52” or “Ann Arbor Ambassador with 48 lines”. The other names should include whatever the user ought to be able to specify to get this terminal type, such as ‘vt52’ or ‘aaa-48’. See section Terminal Type Name Conventions, for information on how to choose terminal type names.

After the terminal type names come the terminal capabilities, separated by colons and with a colon after the last one. Each capability has a two-letter name, such as ‘cm’ for “cursor motion string” or ‘li’ for “number of display lines”.

2.2 Writing the Capabilities

There are three kinds of capabilities: flags, numbers, and strings. Each kind has its own way of being written in the description. Each defined capability has by convention a particular kind of value; for example, ‘li’ always has a numeric value and ‘cm’ always a string value.

A flag capability is thought of as having a boolean value: the value is true if the capability is present, false if not. When the capability is present, just write its name between two colons.

A numeric capability has a value which is a nonnegative number. Write the capability name, a ‘#’, and the number, between two colons. For example, ‘…:li#48:…’ is how you specify the ‘li’ capability for 48 lines.

A string-valued capability has a value which is a sequence of characters. Usually these are the characters used to perform some display operation. Write the capability name, a ‘=’, and the characters of the value, between two colons. For example, ‘…:cm=\E[%i%d;%dH:…’ is how the cursor motion command for a standard ANSI terminal would be specified.

Special characters in the string value can be expressed using ‘\’-escape sequences as in C; in addition, ‘\E’ stands for <ESC>. ‘^’ is also a kind of escape character; ‘^’ followed by char stands for the control-equivalent of char. Thus, ‘^a’ stands for the character control-a, just like ‘\001’. ‘\’ and ‘^’ themselves can be represented as ‘\\’ and ‘\^’.

To include a colon in the string, you must write ‘\072’. You might ask, “Why can’t ‘\:’ be used to represent a colon?” The reason is that the interrogation functions do not count slashes while looking for a capability. Even if ‘:ce=ab\:cd:’ were interpreted as giving the ‘ce’ capability the value ‘ab:cd’, it would also appear to define ‘cd’ as a flag.

The string value will often contain digits at the front to specify padding (see section Padding) and/or ‘%’-sequences within to specify how to encode parameters (see section Filling In Parameters). Although these things are not to be output literally to the terminal, they are considered part of the value of the capability. They are special only when the string value is processed by tputs, tparam or tgoto. By contrast, ‘\’ and ‘^’ are considered part of the syntax for specifying the characters in the string.

Let’s look at the VT52 example again:

dw|vt52|DEC vt52:\
        :cr=^M:do=^J:nl=^J:bl=^G:\
        :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
        :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:

Here we see the numeric-valued capabilities ‘co’ and ‘li’, the flags ‘bs’ and ‘pt’, and many string-valued capabilities. Most of the strings start with <ESC> represented as ‘\E’. The rest contain control characters represented using ‘^’. The meanings of the individual capabilities are defined elsewhere (see section Definitions of the Terminal Capabilities).

2.3 Terminal Type Name Conventions

There are conventions for choosing names of terminal types. For one thing, all letters should be in lower case. The terminal type for a terminal in its most usual or most fundamental mode of operation should not have a hyphen in it.

If the same terminal has other modes of operation which require different terminal descriptions, these variant descriptions are given names made by adding suffixes with hyphens. Such alternate descriptions are used for two reasons:

• When the terminal has a switch that changes its behavior. Since the computer cannot tell how the switch is set, the user must tell the computer by choosing the appropriate terminal type name.

  For example, the VT-100 has a setup flag that controls whether the cursor wraps at the right margin. If this flag is set to “wrap”, you must use the terminal type ‘vt100-am’. Otherwise you must use ‘vt100-nam’. Plain ‘vt100’ is defined as a synonym for either ‘vt100-am’ or ‘vt100-nam’ depending on the preferences of the local site.

  The standard suffix ‘-am’ stands for “automatic margins”.

• To give the user a choice in how to use the terminal. This is done when the terminal has a switch that the computer normally controls.

  For example, the Ann Arbor Ambassador can be configured with many screen sizes ranging from 20 to 60 lines. Fewer lines make bigger characters but more lines let you see more of what you are editing. As a result, users have different preferences. Therefore, termcap provides terminal types for many screen sizes. If you choose type ‘aaa-30’, the terminal will be configured to use 30 lines; if you choose ‘aaa-48’, 48 lines will be used, and so on.

Here is a list of standard suffixes and their conventional meanings:

‘-w’

Short for “wide”. This is a mode that gives the terminal more columns than usual. This is normally a user option.

‘-am’

“Automatic margins”. This is an alternate description for use when the terminal’s margin-wrap switch is on; it contains the ‘am’ flag. The implication is that normally the switch is off and the usual description for the terminal says that the switch is off.

‘-nam’

“No automatic margins”. The opposite of ‘-am’, this names an alternative description which lacks the ‘am’ flag. This implies that the terminal is normally operated with the margin-wrap switch turned on, and the normal description of the terminal says so.

‘-na’

“No arrows”. This terminal description initializes the terminal to keep its arrow keys in local mode. This is a user option.

‘-rv’

“Reverse video”. This terminal description causes text output for normal video to appear as reverse, and text output for reverse video to come out as normal. Often this description differs from the usual one by interchanging the two strings which turn reverse video on and off.

This is a user option; you can choose either the “reverse video” variant terminal type or the normal terminal type, and termcap will obey.

‘-s’

“Status”. Says to enable use of a status line which ordinary output does not touch (see section Status Line).

Some terminals have a special line that is used only as a status line. For these terminals, there is no need for a ‘-s’ variant; the status line commands should be defined by default. On other terminals, enabling a status line means removing one screen line from ordinary use and reducing the effective screen height. For these terminals, the user can choose the ‘-s’ variant type to request use of a status line.

‘-nlines’

Says to operate with nlines lines on the screen, for terminals such as the Ambassador which provide this as an option. Normally this is a user option; by choosing the terminal type, you control how many lines termcap will use.

‘-npagesp’

Says that the terminal has npages pages worth of screen memory, for terminals where this is a hardware option.

‘-unk’

Says that description is not for direct use, but only for reference in ‘tc’ capabilities. Such a description is a kind of subroutine, because it describes the common characteristics of several variant descriptions that would use other suffixes in place of ‘-unk’.

2.4 Inheriting from Related Descriptions

When two terminal descriptions are similar, their identical parts do not need to be given twice. Instead, one of the two can be defined in terms of the other, using the ‘tc’ capability. We say that one description refers to the other, or inherits from the other.

The ‘tc’ capability must be the last one in the terminal description, and its value is a string which is the name of another terminal type which is referred to. For example,

N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
        :ti=\E[2J\E[30;0;0;30p:\
        :te=\E[60;0;0;30p\E[30;1H\E[J:\
        :li#30:tc=aaa-unk:

defines the terminal type ‘aaa-30’ (also known as plain ‘aaa’) in terms of ‘aaa-unk’, which defines everything about the Ambassador that is independent of screen height. The types ‘aaa-36’, ‘aaa-48’ and so on for other screen heights are likewise defined to inherit from ‘aaa-unk’.

The capabilities overridden by ‘aaa-30’ include ‘li’, which says how many lines there are, and ‘ti’ and ‘te’, which configure the terminal to use that many lines.

The effective terminal description for type ‘aaa’ consists of the text shown above followed by the text of the description of ‘aaa-unk’. The ‘tc’ capability is handled automatically by tgetent, which finds the description thus referenced and combines the two descriptions (see section Finding a Terminal Description: tgetent). Therefore, only the implementor of the terminal descriptions needs to think about using ‘tc’. Users and application programmers do not need to be concerned with it.

Since the reference terminal description is used last, capabilities specified in the referring description override any specifications of the same capabilities in the reference description.

The referring description can cancel out a capability without specifying any new value for it by means of a special trick. Write the capability in the referring description, with the character ‘@’ after the capability name, as follows:

NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
        :am@:tc=aaa-30:

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.