/etc/termcap look like.
--- The Detailed Node Listing ---
The Termcap Library
Padding
tputs to output the needed padding.
Filling In Parameters
Sending Display Commands with Parameters
The Format of the Data Base
Definitions of the Terminal Capabilities
Termcap is a library and data base that enables programs to use display terminals in a terminal-independent manner. It originated in Berkeley Unix.
The termcap data base describes the capabilities of hundreds of different display terminals in great detail. Some examples of the information recorded for a terminal could include how many columns wide it is, what string to send to move the cursor to an arbitrary position (including how to encode the row and column numbers), how to scroll the screen up one or several lines, and how much padding is needed for such a scrolling operation.
The termcap library is provided for easy access this data base in programs that want to do terminal-independent character-based display output.
This manual describes the GNU version of the termcap library, which has some extensions over the Unix version. All the extensions are identified as such, so this manual also tells you how to use the Unix termcap.
The GNU version of the termcap library is available free as source code,
for use in free programs, and runs on Unix and VMS systems (at least). You
can find it in the GNU Emacs distribution in the files termcap.c and
tparam.c.
This manual was written for the GNU project, whose goal is to develop a
complete free operating system upward-compatible with Unix for user
programs. The project is approximately two thirds complete. For more
information on the GNU project, including the GNU Emacs editor and the
mostly-portable optimizing C compiler, send one dollar to
Free Software Foundation 675 Mass Ave Cambridge, MA 02139
The termcap library is the application programmer's interface to the termcap data base. It contains functions for the following purposes:
tgetent).
tgetnum, tgetflag, tgetstr).
tputs).
tparam,
tgoto).
To use the termcap library in a program, you need two kinds of preparation:
On GNU systems, it suffices to include the header file
termcap.h in each source file that uses these functions and
variables.
On Unix systems, there is often no such header file. Then you must
explictly declare the variables as external. You can do likewise for
the functions, or let them be implicitly declared and cast their
values from type int to the appropriate type.
We illustrate the declarations of the individual termcap library functions with ANSI C prototypes because they show how to pass the arguments. If you are not using the GNU C compiler, you probably cannot use function prototypes, so omit the argument types and names from your declarations.
-ltermcap or -ltermlib as an argument when linking will
do this.
tgetentAn application program that is going to use termcap must first look up the
description of the terminal type in use. This is done by calling
tgetent, whose declaration in ANSI Standard C looks like:
int tgetent (char *buffer, char *termtype);
This function finds the description and remembers it internally so that you can interrogate it about specific terminal capabilities (see Interrogate).
The argument termtype is a string which is the name for the type of
terminal to look up. Usually you would obtain this from the environment
variable TERM using getenv ("TERM").
If you are using the GNU version of termcap, you can alternatively ask
tgetent to allocate enough space. Pass a null pointer for
buffer, and tgetent itself allocates the storage using
malloc. There is no way to get the address that was allocated,
and you shouldn't try to free the storage.
With the Unix version of termcap, you must allocate space for the description yourself and pass the address of the space as the argument buffer. There is no way you can tell how much space is needed, so the convention is to allocate a buffer 2048 characters long and assume that is enough. (Formerly the convention was to allocate 1024 characters and assume that was enough. But one day, for one kind of terminal, that was not enough.)
No matter how the space to store the description has been obtained,
termcap records its address internally for use when you later interrogate
the description with tgetnum, tgetstr or tgetflag. If
the buffer was allocated by termcap, it will be freed by termcap too if you
call tgetent again. If the buffer was provided by you, you must
make sure that its contents remain unchanged for as long as you still plan
to interrogate the description.
The return value of tgetent is -1 if there is some difficulty
accessing the data base of terminal types, 0 if the data base is accessible
but the specified type is not defined in it, and some other value
otherwise.
Here is how you might use the function tgetent:
#ifdef unix
static char term_buffer[2048];
#else
#define term_buffer 0
#endif
init_terminal_data ()
{
char *termtype = getenv ("TERM");
int success;
if (termtype == 0)
fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
success = tgetent (term_buffer, termtype);
if (success < 0)
fatal ("Could not access the termcap data base.\n");
if (success == 0)
fatal ("Terminal type `%s' is not defined.\n", termtype);
}
Here we assume the function fatal prints an error message and exits.
If the environment variable TERMCAP is defined, its value is used to
override the terminal type data base. The function tgetent checks
the value of TERMCAP automatically. If the value starts with
/ then it is taken as a file name to use as the data base file,
instead of /etc/termcap which is the standard data base. If the
value does not start with / then it is itself used as the terminal
description, provided that the terminal type termtype is among the
types it claims to apply to. See Data Base, for information on the
format of a terminal description.
Each piece of information recorded in a terminal description is called a
capability. Each defined terminal capability has a two-letter code
name and a specific meaning. For example, the number of columns is named
co. See Capabilities, for definitions of all the standard
capability names.
Once you have found the proper terminal description with tgetent
(see Find), your application program must interrogate it for
various terminal capabilities. You must specify the two-letter code of
the capability whose value you seek.
Capability values can be numeric, boolean (capability is either present or
absent) or strings. Any particular capability always has the same value
type; for example, co always has a numeric value, while am
(automatic wrap at margin) is always a flag, and cm (cursor motion
command) always has a string value. The documentation of each capability
says which type of value it has.
There are three functions to use to get the value of a capability,
depending on the type of value the capability has. Here are their
declarations in ANSI C:
int tgetnum (char *name); int tgetflag (char *name); char *tgetstr (char *name, char **area);
tgetnum
tgetnum to get a capability value that is numeric. The
argument name is the two-letter code name of the capability. If
the capability is present, tgetnum returns the numeric value
(which is nonnegative). If the capability is not mentioned in the
terminal description, tgetnum returns -1.
tgetflag
tgetflag to get a boolean value. If the capability
name is present in the terminal description, tgetflag
returns 1; otherwise, it returns 0.
tgetstr
tgetstr to get a string value. It returns a pointer to a
string which is the capability value, or a null pointer if the
capability is not present in the terminal description.
There are two ways tgetstr can find space to store the string value:
tgetstr to allocate the space. Pass a null
pointer for the argument area, and tgetstr will use
malloc to allocate storage big enough for the value.
Termcap will never free this storage or refer to it again; you
should free it when you are finished with it.
This method is more robust, since there is no need to guess how much space is needed. But it is supported only by the GNU termcap library.
char *. Before calling
tgetstr, initialize the variable to point at available space.
Then tgetstr will store the string value in that space and will
increment the pointer variable to point after the space that has been
used. You can use the same pointer variable for many calls to
tgetstr.
There is no way to determine how much space is needed for a single
string, and no way for you to prevent or handle overflow of the area
you have provided. However, you can be sure that the total size of
all the string values you will obtain from the terminal description is
no greater than the size of the description (unless you get the same
capability twice). You can determine that size with strlen on
the buffer you provided to tgetent. See below for an example.
Providing the space yourself is the only method supported by the Unix version of termcap.
Note that you do not have to specify a terminal type or terminal
description for the interrogation functions. They automatically use the
description found by the most recent call to tgetent.
Here is an example of interrogating a terminal description for various
capabilities, with conditionals to select between the Unix and GNU methods
of providing buffer space.
char *tgetstr ();
char *cl_string, *cm_string;
int height;
int width;
int auto_wrap;
char PC; /* For tputs. */
char *BC; /* For tgoto. */
char *UP;
interrogate_terminal ()
{
#ifdef UNIX
/* Here we assume that an explicit term_buffer
was provided to tgetent. */
char *buffer
= (char *) malloc (strlen (term_buffer));
#define BUFFADDR &buffer
#else
#define BUFFADDR 0
#endif
char *temp;
/* Extract information we will use. */
cl_string = tgetstr ("cl", BUFFADDR);
cm_string = tgetstr ("cm", BUFFADDR);
auto_wrap = tgetflag ("am");
height = tgetnum ("li");
width = tgetnum ("co");
/* Extract information that termcap functions use. */
temp = tgetstr ("pc", BUFFADDR);
PC = temp ? *temp : 0;
BC = tgetstr ("le", BUFFADDR);
UP = tgetstr ("up", BUFFADDR);
}
See Padding, for information on the variable PC. See Using Parameters, for information on UP and BC.
Before starting to output commands to a terminal using termcap, an application program should do two things:
PC and ospeed for
padding (see Output Padding) and UP and BC for
cursor motion (see tgoto).
To turn off output processing in Berkeley Unix you would use ioctl
with code TIOCLSET to set the bit named LLITOUT, and clear
the bits ANYDELAY using TIOCSETN. In POSIX or System V, you
must clear the bit named OPOST. Refer to the system documentation
for details.
If you do not set the terminal flags properly, some older terminals will not work. This is because their commands may contain the characters that normally signify newline, carriage return and horizontal tab--characters which the kernel thinks it ought to modify before output.
When you change the kernel's terminal flags, you must arrange to restore
them to their normal state when your program exits. This implies that the
program must catch fatal signals such as SIGQUIT and SIGINT
and restore the old terminal flags before actually terminating.
Modern terminals' commands do not use these special characters, so if you do not care about problems with old terminals, you can leave the kernel's terminal flags unaltered.
Padding means outputting null characters following a terminal display
command that takes a long time to execute. The terminal description says
which commands require padding and how much; the function tputs,
described below, outputs a terminal command while extracting from it the
padding information, and then outputs the padding that is necessary.
tputs to output the needed padding.
Most types of terminal have commands that take longer to execute than they do to send over a high-speed line. For example, clearing the screen may take 20msec once the entire command is received. During that time, on a 9600 bps line, the terminal could receive about 20 additional output characters while still busy clearing the screen. Every terminal has a certain amount of buffering capacity to remember output characters that cannot be processed yet, but too many slow commands in a row can cause the buffer to fill up. Then any additional output that cannot be processed immediately will be lost.
To avoid this problem, we normally follow each display command with enough useless charaters (usually null characters) to fill up the time that the display command needs to execute. This does the job if the terminal throws away null characters without using up space in the buffer (which most terminals do). If enough padding is used, no output can ever be lost. The right amount of padding avoids loss of output without slowing down operation, since the time used to transmit padding is time that nothing else could be done.
The number of padding characters needed for an operation depends on the line speed. In fact, it is proportional to the line speed. A 9600 baud line transmits about one character per msec, so the clear screen command in the example above would need about 20 characters of padding. At 1200 baud, however, only about 3 characters of padding are needed to fill up 20msec.
There are several common manifestations of insufficient padding.
I-search: ^Q- at the bottom of the screen.
This means that the terminal thought its buffer was getting full of display commands, so it tried to tell the computer to stop sending any.
This means that the buffer did get full, and some commands were lost. Many changeable factors can change which ones are lost.
This means that a high enough speed permits commands to arrive faster than they can be executed.
Although any obscure command on an obscure terminal might lack padding,
in practice problems arise most often from the clearing commands
cl and cd (see Clearing), the scrolling commands
sf and sr (see Scrolling), and the line insert/delete
commands al and dl (see Insdel Line).
Occasionally the terminal description fails to define sf and some
programs will use do instead, so you may get a problem with
do. If so, first define sf just like do, then
add some padding to sf.
The best strategy is to add a lot of padding at first, perhaps 200 msec. This is much more than enough; in fact, it should cause a visible slowdown. (If you don't see a slowdown, the change has not taken effect; see Changing.) If this makes the problem go away, you have found the right place to add padding; now reduce the amount until the problem comes back, then increase it again. If the problem remains, either it is in some other capability or it is not a matter of padding at all.
Keep in mind that on many terminals the correct padding for insert/delete line or for scrolling is cursor-position dependent. If you get problems from scrolling a large region of the screen but not from scrolling a small part (just a few lines moving), it may mean that fixed padding should be replaced with position-dependent padding.
In the terminal description, the amount of padding required by each display command is recorded as a sequence of digits at the front of the command. These digits specify the padding time in milliseconds (msec). They can be followed optionally by a decimal point and one more digit, which is a number of tenths of msec.
Sometimes the padding needed by a command depends on the cursor position.
For example, the time taken by an "insert line" command is usually
proportional to the number of lines that need to be moved down or cleared.
An asterisk (*) following the padding time says that the time
should be multiplied by the number of screen lines affected by the command.
:al=1.3*\E[L:
is used to describe the "insert line" command for a certain terminal.
The padding required is 1.3 msec per line affected. The command itself is
<ESC> [ L.
The padding time specified in this way tells tputs how many pad
characters to output. See Output Padding.
Two special capability values affect padding for all commands. These are
the pc and pb. The variable pc specifies the
character to pad with, and pb the speed below which no padding is
needed. The defaults for these variables, a null character and 0,
are correct for most terminals. See Pad Specs.
tputsUse the termcap function tputs to output a string containing an
optional padding spec of the form described above (see Describe Padding). The function tputs strips off and decodes the padding
spec, outputs the rest of the string, and then outputs the appropriate
padding. Here is its declaration in ANSI C:
char PC; short ospeed; int tputs (char *string, int nlines, int (*outfun) ());
Here string is the string (including padding spec) to be output;
nlines is the number of lines affected by the operation, which is
used to multiply the amount of padding if the padding spec ends with a
*. Finally, outfun is a function (such as fputchar)
that is called to output each character. When actually called,
outfun should expect one argument, a character.
The operation of tputs is controlled by two global variables,
ospeed and PC. The value of ospeed is supposed to be
the terminal output speed, encoded as in the ioctl system call which
gets the speed information. This is needed to compute the number of
padding characters. The value of PC is the character used for
padding.
You are responsible for storing suitable values into these variables before
using tputs. The value stored into the PC variable should be
taken from the pc capability in the terminal description (see Pad Specs). Store zero in PC if there is no pc
capability.
The argument nlines requires some thought. Normally, it should be
the number of lines whose contents will be cleared or moved by the command.
For cursor motion commands, or commands that do editing within one line,
use the value 1. For most commands that affect multiple lines, such as
al (insert a line) and cd (clear from the cursor to the end
of the screen), nlines should be the screen height minus the current
vertical position (origin 0). For multiple insert and scroll commands such
as AL (insert multiple lines), that same value for nlines is
correct; the number of lines being inserted is not correct.
If a "scroll window" feature is used to reduce the number of lines affected by a command, the value of nlines should take this into account. This is because the delay time required depends on how much work the terminal has to do, and the scroll window feature reduces the work. See Scrolling.
Commands such as ic and dc (insert or delete characters) are
problematical because the padding needed by these commands is proportional
to the number of characters affected, which is the number of columns from
the cursor to the end of the line. It would be nice to have a way to
specify such a dependence, and there is no need for dependence on vertical
position in these commands, so it is an obvious idea to say that for these
commands nlines should really be the number of columns affected.
However, the definition of termcap clearly says that nlines is always
the number of lines affected, even in this case, where it is always 1. It
is not easy to change this rule now, because too many programs and terminal
descriptions have been written to follow it.
Because nlines is always 1 for the ic and dc strings,
there is no reason for them to use *, but some of them do. These
should be corrected by deleting the *. If, some day, such entries
have disappeared, it may be possible to change to a more useful convention
for the nlines argument for these operations without breaking any
programs.
Some terminal control strings require numeric parameters. For
example, when you move the cursor, you need to say what horizontal and
vertical positions to move it to. The value of the terminal's cm
capability, which says how to move the cursor, cannot simply be a string of
characters; it must say how to express the cursor position numbers and
where to put them within the command.
The specifications of termcap include conventions as to which string-valued
capabilities require parameters, how many parameters, and what the
parameters mean; for example, it defines the cm string to take
two parameters, the vertical and horizontal positions, with 0,0 being the
upper left corner. These conventions are described where the individual
commands are documented.
Termcap also defines a language used within the capability definition for
specifying how and where to encode the parameters for output. This language
uses character sequences starting with %. (This is the same idea as
printf, but the details are different.) The language for parameter
encoding is described in this section.
A program that is doing display output calls the functions tparam or
tgoto to encode parameters according to the specifications. These
functions produce a string containing the actual commands to be output (as
well a padding spec which must be processed with tputs;
see Padding).
A terminal command string that requires parameters contains special
character sequences starting with % to say how to encode the
parameters. These sequences control the actions of tparam and
tgoto.
The parameters values passed to tparam or tgoto are
considered to form a vector. A pointer into this vector determines
the next parameter to be processed. Some of the %-sequences
encode one parameter and advance the pointer to the next parameter.
Other %-sequences alter the pointer or alter the parameter
values without generating output.
For example, the cm string for a standard ANSI terminal is written
as \E[%i%d;%dH. (\E stands for <ESC>.) cm by
convention always requires two parameters, the vertical and horizontal goal
positions, so this string specifies the encoding of two parameters. Here
%i increments the two values supplied, and each %d encodes
one of the values in decimal. If the cursor position values 20,58 are
encoded with this string, the result is \E[21;59H.
First, here are the %-sequences that generate output. Except for
%%, each of them encodes one parameter and advances the pointer
to the following parameter.
%%
%. This is the only way to represent a literal
% in a terminal command with parameters. %% does not
use up a parameter.
%d
printf, output the next parameter in decimal.
%2
%02d in printf: output the next parameter in
decimal, and always use at least two digits.
%3
%03d in printf: output the next parameter in
decimal, and always use at least three digits. Note that %4
and so on are not defined.
%.
%c in printf.
%+char
%+ represents 0 as a space,
1 as !, etc.
The following %-sequences specify alteration of the parameters
(their values, or their order) rather than encoding a parameter for output.
They generate no output; they are used only for their side effects
on the parameters. Also, they do not advance the "next parameter" pointer
except as explicitly stated. Only %i, %r and %> are
defined in standard Unix termcap. The others are GNU extensions.
%i
%i%d,%d would
output two parameters with 1 for 0, 2 for 1, etc.
%r
%s
%b
%b more than once, you can back up any number of
parameters, and you can refer to each parameter any number of times.
%>c1c2
%a op type pos
Spaces are used above to separate the operands for clarity; the spaces don't appear in the data base, where this sequence is exactly five characters long.
The character op says what kind of arithmetic operation to perform. It can be any of these characters:
=
+
-
*
/
The "other operand" may be another parameter's value or a constant; the character type says which. It can be:
p
A as pos means the parameter after the
next one; the character ? means the parameter before the
next one.
c
The following %-sequences are special purpose hacks to compensate
for the weird designs of obscure terminals. They modify the next parameter
or the next two parameters but do not generate output and do not use up any
parameters. %m is a GNU extension; the others are defined in
standard Unix termcap.
%n
%m
%B
parm = (parm / 10) * 16 + parm % 10;
%D
parm -= 2 * (parm % 16);
The termcap library functions tparam and tgoto serve as the
analog of printf for terminal string parameters. The newer function
tparam is a GNU extension, more general but missing from Unix
termcap. The original parameter-encoding function is tgoto, which
is preferable for cursor motion.
tparamThe function tparam can encode display commands with any number of
parameters and allows you to specify the buffer space. It is the preferred
function for encoding parameters for all but the cm capability. Its
ANSI C declaration is as follows:
char *tparam (char *ctlstring, char *buffer, int size, int parm1,...)
The arguments are a control string ctlstring (the value of a terminal
capability, presumably), an output buffer buffer and size, and
any number of integer parameters to be encoded. The effect of
tparam is to copy the control string into the buffer, encoding
parameters according to the % sequences in the control string.
You describe the output buffer by its address, buffer, and its size
in bytes, size. If the buffer is not big enough for the data to be
stored in it, tparam calls malloc to get a larger buffer. In
either case, tparam returns the address of the buffer it ultimately
uses. If the value equals buffer, your original buffer was used.
Otherwise, a new buffer was allocated, and you must free it after you are
done with printing the results. If you pass zero for size and
buffer, tparam always allocates the space with malloc.
All capabilities that require parameters also have the ability to specify
padding, so you should use tputs to output the string produced by
tparam. See Padding. Here is an example.
{
char *buf;
char buffer[40];
buf = tparam (command, buffer, 40, parm);
tputs (buf, 1, fputchar);
if (buf != buffer)
free (buf);
}
If a parameter whose value is zero is encoded with %.-style
encoding, the result is a null character, which will confuse tputs.
This would be a serious problem, but luckily %. encoding is used
only by a few old models of terminal, and only for the cm
capability. To solve the problem, use tgoto rather than
tparam to encode the cm capability.
tgotoThe special case of cursor motion is handled by tgoto. There
are two reasons why you might choose to use tgoto:
tparam.
cm capability, since tgoto has a special feature
to avoid problems with null characters, tabs and newlines on certain old
terminal types that use %. encoding for that capability.
Here is how tgoto might be declared in ANSI C:
char *tgoto (char *cstring, int hpos, int vpos)
There are three arguments, the terminal description's cm string and
the two cursor position numbers; tgoto computes the parametrized
string in an internal static buffer and returns the address of that buffer.
The next time you use tgoto the same buffer will be reused.
Parameters encoded with %. encoding can generate null characters,
tabs or newlines. These might cause trouble: the null character because
tputs would think that was the end of the string, the tab because
the kernel or other software might expand it into spaces, and the newline
becaue the kernel might add a carriage-return, or padding characters
normally used for a newline. To prevent such problems, tgoto is
careful to avoid these characters. Here is how this works: if the target
cursor position value is such as to cause a problem (that is to say, zero,
nine or ten), tgoto increments it by one, then compensates by
appending a string to move the cursor back or up one position.
The compensation strings to use for moving back or up are found in global
variables named BC and UP. These are actual external C
variables with upper case names; they are declared char *. It is up
to you to store suitable values in them, normally obtained from the
le and up terminal capabilities in the terminal description
with tgetstr. Alternatively, if these two variables are both zero,
the feature of avoiding nulls, tabs and newlines is turned off.
It is safe to use tgoto for commands other than cm only if
you have stored zero in BC and UP.
Note that tgoto reverses the order of its operands: the horizontal
position comes before the vertical position in the arguments to
tgoto, even though the vertical position comes before the horizontal
in the parameters of the cm string. If you use tgoto with a
command such as AL that takes one parameter, you must pass the
parameter to tgoto as the "vertical position".
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 Capabilities) and their values describe the terminal.
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 Naming, 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".
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 Padding) and/or %-sequences within to specify how to encode
parameters (see 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 Capabilities).
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:
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".
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
-am
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
-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
-rv
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
Some terminals have a special line that is used only as a status line.
For these terminals, there is no need for an -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
-npagesp
-unk
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.
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 Find). 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:
Each application program must read the terminal description from the data base, so a change in the data base is effective for all jobs started after the change is made.
The change will usually have no effect on a job that have been in existence since before the change. The program probably read the terminal description once, when it was started, and is continuing to use what it read then. If the program does not have a feature for reexamining the data base, then you will need to run it again (probably killing the old job).
If the description in use is coming from the TERMCAP environment
variable, then the data base file is effectively overridden, and changes in
it will have no effect until you change the TERMCAP variable as
well. For example, some users' .login files automatically copy the
terminal description into TERMCAP to speed startup of applications.
If you have done this, you will need to change the TERMCAP variable
to make the changed data base take effect.
This section is divided into many subsections, each for one aspect of use of display terminals. For writing a display program, you usually need only check the subsections for the operations you want to use. For writing a terminal description, you must read each subsection and fill in the capabilities described there.
String capabilities that are display commands may require numeric
parameters (see Parameters). Most such capabilities do not use
parameters. When a capability requires parameters, this is explicitly
stated at the beginning of its definition. In simple cases, the first or
second sentence of the definition mentions all the parameters, in the order
they should be given, using a name
for each one. For example, the rp capability is a command that
requires two parameters; its definition begins as follows:
String of commands to output a graphic character c, repeated n times.
In complex cases or when there are many parameters, they are described explicitly.
When a capability is described as obsolete, this means that programs should not be written to look for it, but terminal descriptions should still be written to provide it.
When a capability is described as very obsolete, this means that it should be omitted from terminal descriptions as well.
This section documents the capabilities that describe the basic and nature of the terminal, and also those that are relevant to the output of graphic characters.
os
eo
(On terminals that do not support overstriking, you can always assume
that outputting a space at a position erases whatever character was
previously displayed there.)
gn
network.
Since the generic type cannot say how to do anything interesting with
the terminal, termcap-using programs will always find that the
terminal is too weak to be supported if the user has failed to specify
a real terminal type in place of the generic one. The gn flag
directs these programs to use a different error message: "You have
not specified your real terminal type", rather than "Your terminal
is not powerful enough to be used".
hc
rp
%-sequences to compute the
amount of padding, then generating the result as a number at the front
of the string so that tputs will treat it as padding.
hz
~ cannot be
output on this terminal because it is used for display commands.
Programs handle this flag by checking all text to be output and
replacing each ~ with some other character(s). If this is not
done, the screen will be thoroughly garbled.
The old Hazeltine terminals that required such treatment are probably
very rare today, so you might as well not bother to support this flag.
CC
All the strings of commands in the terminal description should be
written to use the default command character. If you are writing an
application program that changes the command character, use the
CC capability to figure out how to translate all the display
commands to work with the new command character.
Most programs have no reason to look at the CC capability.
xb
A terminal description has two capabilities, co and li,
that describe the screen size in columns and lines. But there is more
to the question of screen size than this.
On some operating systems the "screen" is really a window and the
effective width can vary. On some of these systems, tgetnum
uses the actual width of the window to decide what value to return for
the co capability, overriding what is actually written in the
terminal description. On other systems, it is up to the application
program to check the actual window width using a system call. For
example, on BSD 4.3 systems, the system call ioctl with code
TIOCGWINSZ will tell you the current screen size.
On all window systems, termcap is powerless to advise the application
program if the user resizes the window. Application programs must
deal with this possibility in a system-dependent fashion. On some
systems the C shell handles part of the problem by detecting changes
in window size and setting the TERMCAP environment variable
appropriately. This takes care of application programs that are
started subsequently. It does not help application programs already
running.
On some systems, including BSD 4.3, all programs using a terminal get
a signal named SIGWINCH whenever the screen size changes.
Programs that use termcap should handle this signal by using
ioctl TIOCGWINSZ to learn the new screen size.
co
co capability.
li
Termcap assumes that the terminal has a cursor, a spot on the screen where a visible mark is displayed, and that most display commands take effect at the position of the cursor. It follows that moving the cursor to a specified location is very important.
There are many terminal capabilities for different cursor motion
operations. A terminal description should define as many as possible, but
most programs do not need to use most of them. One capability, cm,
moves the cursor to an arbitrary place on the screen; this by itself is
sufficient for any application as long as there is no need to support
hardcopy terminals or certain old, weak displays that have only relative
motion commands. Use of other cursor motion capabilities is an
optimization, enabling the program to output fewer characters in some
common cases.
If you plan to use the relative cursor motion commands in an application program, you must know what the starting cursor position is. To do this, you must keep track of the cursor position and update the records each time anything is output to the terminal, including graphic characters. In addition, it is necessary to know whether the terminal wraps after writing in the rightmost column. See Wrapping.
One other motion capability needs special mention: nw moves the
cursor to the beginning of the following line, perhaps clearing all the
starting line after the cursor, or perhaps not clearing at all. This
capability is a least common denominator that is probably supported even by
terminals that cannot do most other things such as cm or do.
Even hardcopy terminals can support nw.
cm
All display terminals except a few very obsolete ones support cm,
so it is acceptable for an application program to refuse to operate on
terminals lacking cm.
ho
Every display terminal supports this capability, and many application
programs refuse to operate if the ho capability is missing.
ll
ll string (if it is provided); if moving to home position and
then moving up is the best way to get there, the ll command
will do that.
cr
le
bw flag capability is specified, the effect is undefined if the
cursor is at the left margin; do not use this command there. If
bw is present, this command may be used at the left margin, and
it wraps the cursor to the last column of the preceding line.
nd
am is present.
up
do
Some programs do use do to scroll up one line if used at the
bottom line, if sf is not defined but sr is. This is
only to compensate for certain old, incorrect terminal descriptions.
(In principle this might actually lead to incorrect behavior on other
terminals, but that seems to happen rarely if ever.) But the proper
solution is that the terminal description should define sf as
well as do if the command is suitable for scrolling.
The original idea was that this string would not contain a newline
character and therefore could be used without disabling the kernel's
usual habit of converting of newline into a carriage-return newline
sequence. But many terminal descriptions do use newline in the
do string, so this is not possible; a program which sends the
do string must disable output conversion in the kernel
(see Initialize).
bw
le may be used in column zero
to move to the last column of the preceding line. If this flag
is not present, le should not be used in column zero.
nw
DO, UP, LE, RI
CM
ch
cm in which the
vertical position is not changed. The ch capability is
provided only when it is faster to output than cm would be in
this special case. Programs should not assume most display terminals
have ch.
cv
cm in which the horizontal
position is not changed. The cv capability is provided only
when it is faster to output than cm would be in this special
case. Programs should not assume most display terminals have
cv.
sc
rc should be provided also. Most
terminals have neither.
rc
sc should be provided
also. Most terminals have neither.
ff
ta
bt
The following obsolete capabilities should be included in terminal descriptions when appropriate, but should not be looked at by new programs.
nc
cr. This flag is needed because
old programs assume, when the cr capability is missing, that
ASCII carriage return can be used for the purpose. We use nc
to tell the old programs that carriage return may not be used.
New programs should not assume any default for cr, so they need
not look at nc. However, descriptions should contain nc
whenever they do not contain cr.
xt
ta capability is missing, that ASCII tab can be used for
the purpose. We use xt to tell the old programs not to use tab.
New programs should not assume any default for ta, so they need
not look at xt in connection with cursor motion. Note that
xt also has implications for standout mode (see Standout).
It is obsolete in regard to cursor motion but not in regard to
standout.
In fact, xt means that the terminal is a Teleray 1061.
bc
le capability.
bs
le instead.
nl
do or sf, and ignore nl.
If there is no nl capability, some old programs assume they can
use the newline character for this purpose. These programs follow a
bad practice, but because they exist, it is still desirable to define
the nl capability in a terminal description if the best way to
move down is not a newline.
Wrapping means moving the cursor from the right margin to the left margin of the following line. Some terminals wrap automatically when a graphic character is output in the last column, while others do not. Most application programs that use termcap need to know whether the terminal wraps. There are two special flag capabilities to describe what the terminal does when a graphic character is output in the last column.
am
If am is not present, writing in the last column leaves the
cursor at the place where the character was written.
Writing in the last column of the last line should be avoided on
terminals with am, as it may or may not cause scrolling to
occur (see Scrolling). Scrolling is surely not what you would
intend.
If your program needs to check the am flag, then it also needs
to check the xn flag which indicates that wrapping happens in a
strange way. Many common terminals have the xn flag.
xn
On Concept-100 terminals, output in the last column wraps the cursor
almost like an ordinary am terminal. But if the next thing
output is a newline, it is ignored.
DEC VT-100 terminals (when the wrap switch is on) do a different strange thing: the cursor wraps only if the next thing output is another graphic character. In fact, the wrap occurs when the following graphic character is received by the terminal, before the character is placed on the screen.
On both of these terminals, after writing in the last column a
following graphic character will be displayed in the first column of
the following line. But the effect of relative cursor motion
characters such as newline or backspace at such a time depends on the
terminal. The effect of erase or scrolling commands also depends on
the terminal. You can't assume anything about what they will do on a
terminal that has xn. So, to be safe, you should never do
these things at such a time on such a terminal.
To be sure of reliable results on a terminal which has the xn
flag, output a cm absolute positioning command after writing in
the last column. Another safe thing to do is to output carriage-return
newline, which will leave the cursor at the beginning of the following
line.
LP
LP
indicates the DEC flavor of xn strangeness.
Scrolling means moving the contents of the screen up or down one or more lines. Moving the contents up is forward scrolling; moving them down is reverse scrolling.
Scrolling happens after each line of output during ordinary output on most display terminals. But in an application program that uses termcap for random-access output, scrolling happens only when explicitly requested with the commands in this section.
Some terminals have a scroll region feature. This lets you limit
the effect of scrolling to a specified range of lines. Lines outside the
range are unaffected when scrolling happens. The scroll region feature
is available if either cs or cS is present.
sf
sr
do
do to do the work of sf.
This is not really correct--it is an attempt to compensate for the
absence of a sf command in some old terminal descriptions.
Since these terminal descriptions do define sr, perhaps at one
time the definition of do was different and it could be used
for scrolling as well. But it isn't desirable to combine these two
functions in one capability, since scrolling often requires more
padding than simply moving the cursor down. Defining sf and
do separately allows you to specify the padding properly.
Also, all sources agree that do should not be relied on to do
scrolling.
So the best approach is to add sf capabilities to the
descriptions of these terminals, copying the definition of do
if that does scroll.
SF
SR
cs
Do not try to move the cursor outside the scroll region. The region
remains set until explicitly removed. To remove the scroll region,
use another cs command specifying the full height of the
screen.
The cursor position is undefined after the cs command is set,
so position the cursor with cm immediately afterward.
cS
cs were used.
Four parameters are required:
This capability is a GNU extension that was invented to allow the Ann
Arbor Ambassador's scroll-region command to be described; it could
also be done by putting non-Unix %-sequences into a cs
string, but that would have confused Unix programs that used the
cs capability with the Unix termcap. Currently only GNU Emacs
uses the cS capability.
ns
The terminal may be able to scroll even if it does not normally do so.
If the sf capability is provided, it can be used for scrolling
regardless of ns.
da
The da and db flags do not, strictly speaking, affect
how to scroll. But programs that scroll usually need to clear the
lines scrolled onto the screen, if these flags are present.
db
lm
Any terminal description that defines SF should also define sf;
likewise for SR and sr. However, many terminals can only
scroll by one line at a time, so it is common to find sf and not
SF, or sr without SR.
Therefore, all programs that use the scrolling facilities should be
prepared to work with sf in the case that SF is absent, and
likewise with sr. On the other hand, an application program that
uses only sf and not SF is acceptable, though slow on some
terminals.
When outputting a scroll command with tputs, the nlines
argument should be the total number of lines in the portion of the screen
being scrolled. Very often these commands require padding proportional to
this number of lines. See Padding.
A window, in termcap, is a rectangular portion of the screen to which all display operations are restricted. Wrapping, clearing, scrolling, insertion and deletion all operate as if the specified window were all the screen there was.
wi
Most terminals do not support windows.
There are several terminal capabilities for clearing parts of the screen
to blank. All display terminals support the cl string, and most
display terminals support all of these capabilities.
cl
cd
ce
ec
Clear to end of line (ce) is extremely important in programs that
maintain an updating display. Nearly all display terminals support this
operation, so it is acceptable for a an application program to refuse to
work if ce is not present. However, if you do not want this
limitation, you can accomplish clearing to end of line by outputting spaces
until you reach the right margin. In order to do this, you must know the
current horizontal position. Also, this technique assumes that writing a
space will erase. But this happens to be true on all the display terminals
that fail to support ce.
Inserting a line means creating a blank line in the middle of the screen, and pushing the existing lines of text apart. In fact, the lines above the insertion point do not change, while the lines below move down, and one is normally lost at the bottom of the screen.
Deleting a line means causing the line to disappear from the screen,
closing up the gap by moving the lines below it upward. A new line
appears at the bottom of the screen. Usually this line is blank, but
on terminals with the db flag it may be a line previously moved
off the screen bottom by scrolling or line insertion.
Insertion and deletion of lines is useful in programs that maintain an updating display some parts of which may get longer or shorter. They are also useful in editors for scrolling parts of the screen, and for redisplaying after lines of text are killed or inserted.
Many terminals provide commands to insert or delete a single line at the cursor position. Some provide the ability to insert or delete several lines with one command, using the number of lines to insert or delete as a parameter. Always move the cursor to column zero before using any of these commands.
al
db is present (see Scrolling).
The cursor must be at the left margin before this command is used.
This command does not move the cursor.
dl
db
flag, a nonblank line previously pushed off the screen bottom may
reappear at the bottom.
The cursor must be at the left margin before this command is used.
This command does not move the cursor.
AL
al repeated n times, except
that it is as fast as one al.
DL
dl repeated n times, except
that it is as fast as one dl.
Any terminal description that defines AL should also define
al; likewise for DL and dl. However, many terminals
can only insert or delete one line at a time, so it is common to find
al and not AL, or dl without DL.
Therefore, all programs that use the insert and delete facilities should be
prepared to work with al in the case that AL is absent, and
likewise with dl. On the other hand, it is acceptable to write
an application that uses only al and dl and does not look
for AL or DL at all.
If a terminal does not support line insertion and deletion directly, but does support a scroll region, the effect of insertion and deletion can be obtained with scrolling. However, it is up to the individual user program to check for this possibility and use the scrolling commands to get the desired result. It is fairly important to implement this alternate strategy, since it is the only way to get the effect of line insertion and deletion on the popular VT100 terminal.
Insertion and deletion of lines is affected by the scroll region on terminals that have a settable scroll region. This is useful when it is desirable to move any few consecutive lines up or down by a few lines. See Scrolling.
The line pushed off the bottom of the screen is not lost if the terminal
has the db flag capability; instead, it is pushed into display
memory that does not appear on the screen. This is the same thing that
happens when scrolling pushes a line off the bottom of the screen.
Either reverse scrolling or deletion of a line can bring the apparently
lost line back onto the bottom of the screen. If the terminal has the
scroll region feature as well as db, the pushed-out line really
is lost if a scroll region is in effect.
When outputting an insert or delete command with tputs, the
nlines argument should be the total number of lines from the cursor
to the bottom of the screen (or scroll region). Very often these commands
require padding proportional to this number of lines. See Padding.
For AL and DL the nlines argument should not
depend on the number of lines inserted or deleted; only the total number of
lines affected. This is because it is just as fast to insert two or
n lines with AL as to insert one line with al.
Inserting a character means creating a blank space in the middle of a line, and pushing the rest of the line rightward. The character in the rightmost column is lost.
Deleting a character means causing the character to disappear from the screen, closing up the gap by moving the rest of the line leftward. A blank space appears in the rightmost column.
Insertion and deletion of characters is useful in programs that maintain an updating display some parts of which may get longer or shorter. It is also useful in editors for redisplaying the results of editing within a line.
Many terminals provide commands to insert or delete a single character at the cursor position. Some provide the ability to insert or delete several characters with one command, using the number of characters to insert or delete as a parameter.
Many terminals provide an insert mode in which outputting a graphic character has the added effect of inserting a position for that character. A special command string is used to enter insert mode and another is used to exit it. The reason for designing a terminal with an insert mode rather than an insert command is that inserting character positions is usually followed by writing characters into them. With insert mode, this is as fast as simply writing the characters, except for the fixed overhead of entering and leaving insert mode. However, when the line speed is great enough, padding may be required for the graphic characters output in insert mode.
Some terminals require you to enter insert mode and then output a special command for each position to be inserted. Or they may require special commands to be output before or after each graphic character to be inserted.
Deletion of characters is usually accomplished by a straightforward command to delete one or several positions; but on some terminals, it is necessary to enter a special delete mode before using the delete command, and leave delete mode afterward. Sometimes delete mode and insert mode are the same mode.
Some terminals make a distinction between character positions in which a
space character has been output and positions which have been cleared. On
these terminals, the effect of insert or delete character runs to the first
cleared position rather than to the end of the line. In fact, the effect
may run to more than one line if there is no cleared position to stop the
shift on the first line. These terminals are identified by the in
flag capability.
On terminals with the in flag, the technique of skipping over
characters that you know were cleared, and then outputting text later on in
the same line, causes later insert and delete character operations on that
line to do nonstandard things. A program that has any chance of doing this
must check for the in flag and must be careful to write explicit
space characters into the intermediate columns when in is present.
A plethora of terminal capabilities are needed to describe all of this complexity. Here is a list of them all. Following the list, we present an algorithm for programs to use to take proper account of all of these capabilities.
im
If the terminal has no special insert mode, but it can insert
characters with a special command, im should be defined with a
null value, because the vi editor assumes that insertion of a
character is impossible if im is not provided.
New programs should not act like vi. They should pay attention
to im only if it is defined.
ei
im is.
On a few old terminals the same string is used to enter and exit
insert mode. This string turns insert mode on if it was off, and off
it it was on. You can tell these terminals because the ei
string equals the im string. If you want to support these
terminals, you must always remember accurately whether insert mode is
in effect. However, these terminals are obsolete, and it is
reasonable to refuse to support them. On all modern terminals, you
can safely output ei at any time to ensure that insert mode is
turned off.
ic
If outputting a graphic character while in insert mode is sufficient
to insert the character, then the ic capability should be
defined with a null value.
If your terminal offers a choice of ways to insert--either use insert
mode or use a special command--then define im and do not define
ic, since this gives the most efficient operation when several
characters are to be inserted. Do not define both strings, for
that means that both must be used each time insertion is done.
ip
IC
ic string
and a space, n times.
If IC is provided, application programs may use it without first
entering insert mode.
mi
in
An application program can assume that the terminal can do character
insertion if any one of the capabilities IC, im,
ic or ip is provided.
To insert n blank character positions, move the cursor to the place to insert them and follow this algorithm:
IC string is provided, output it with parameter n
and you are finished. Otherwise (or if you don't want to bother to
look for an IC string) follow the remaining steps.
im string, if there is one, unless the terminal is
already in insert mode.
ic string if any.
ip string if any.
ei string, eventually, to exit insert mode. There
is no need to do this right away. If the mi flag is present,
you can move the cursor and the cursor will remain in insert mode;
then you can do more insertion elsewhere without reentering insert
mode.
To insert n graphic characters, position the cursor and follow this algorithm:
IC string is provided, output it with parameter n,
then output the graphic characters, and you are finished. Otherwise
(or if you don't want to bother to look for an IC string)
follow the remaining steps.
im string, if there is one, unless the terminal is
already in insert mode.
ic string if any.
ip string if any.
ei string, eventually, to exit insert mode. There
is no need to do this right away. If the mi flag is present,
you can move the cursor and the cursor will remain in insert mode;
then you can do more insertion elsewhere without reentering insert
mode.
Note that this is not the same as the original Unix termcap specifications
in one respect: it assumes that the IC string can be used without
entering insert mode. This is true as far as I know, and it allows you be
able to avoid entering and leaving insert mode, and also to be able to
avoid the inserted-character padding after the characters that go into the
inserted positions.
Deletion of characters is less complicated; deleting one column is done by
outputting the dc string. However, there may be a delete mode that
must be entered with dm in order to make dc work.
dc
dc is not present, the terminal cannot delete characters.
DC
dc string n times.
Any terminal description that has DC also has dc.
dm
dc can be used at any time (assuming there is
a dc).
ed
dm is.
To delete n character positions, position the cursor and follow these steps:
DC string is present, output it with parameter n
and you are finished. Otherwise, follow the remaining steps.
dm string, unless you know the terminal is already
in delete mode.
dc string n times.
ed string eventually. If the flag capability
mi is present, you can move the cursor and do more deletion
without leaving and reentering delete mode.
As with the IC string, we have departed from the original termcap
specifications by assuming that DC works without entering delete
mode even though dc would not.
If the dm and im capabilities are both present and have the
same value, it means that the terminal has one mode for both insertion and
deletion. It is useful for a program to know this, because then it can do
insertions after deletions, or vice versa, without leaving insert/delete
mode and reentering it.
Appearance modes are modifications to the ways characters are displayed. Typical appearance modes include reverse video, dim, bright, blinking, underlined, invisible, and alternate character set. Each kind of terminal supports various among these, or perhaps none.
For each type of terminal, one appearance mode or combination of them that
looks good for highlighted text is chosen as the standout mode. The
capabilities so and se say how to enter and leave standout
mode. Programs that use appearance modes only to highlight some text
generally use the standout mode so that they can work on as many terminals
as possible. Use of specific appearance modes other than "underlined"
and "alternate character set" is rare.
Terminals that implement appearance modes fall into two general classes as to how they do it.
In some terminals, the presence or absence of any appearance mode is recorded separately for each character position. In these terminals, each graphic character written is given the appearance modes current at the time it is written, and keeps those modes until it is erased or overwritten. There are special commands to turn the appearance modes on or off for characters to be written in the future.
In other terminals, the change of appearance modes is represented by a marker that belongs to a certain screen position but affects all following screen positions until the next marker. These markers are traditionally called magic cookies.
The same capabilities (so, se, mb and so on) for
turning appearance modes on and off are used for both magic-cookie
terminals and per-character terminals. On magic cookie terminals, these
give the commands to write the magic cookies. On per-character terminals,
they change the current modes that affect future output and erasure. Some
simple applications can use these commands without knowing whether or not
they work by means of cookies.
However, a program that maintains and updates a display needs to know
whether the terminal uses magic cookies, and exactly what their effect is.
This information comes from the sg capability.
The sg capability is a numeric capability whose presence indicates
that the terminal uses magic cookies for appearance modes. Its value is
the number of character positions that a magic cookie occupies. Usually
the cookie occupies one or more character positions on the screen, and these
character positions are displayed as blank, but in some terminals the
cookie has zero width.
The sg capability describes both the magic cookie to turn standout
on and the cookie to turn it off. This makes the assumption that both
kinds of cookie have the same width on the screen. If that is not true,
the narrower cookie must be "widened" with spaces until it has the same
width as the other.
On some magic cookie terminals, each line always starts with normal display; in other words, the scope of a magic cookie never extends over more than one line. But on other terminals, one magic cookie affects all the lines below it unless explicitly canceled. Termcap does not define any way to distinguish these two ways magic cookies can work. To be safe, it is best to put a cookie at the beginning of each line.
On some per-character terminals, standout mode or other appearance modes
may be canceled by moving the cursor. On others, moving the cursor has no
effect on the state of the appearance modes. The latter class of terminals
are given the flag capability ms ("can move in standout"). All
programs that might have occasion to move the cursor while appearance modes
are turned on must check for this flag; if it is not present, they should
reset appearance modes to normal before doing cursor motion.
A program that has turned on only standout mode should use se to
reset the standout mode to normal. A program that has turned on only
alternate character set mode should use ae to return it to normal.
If it is possible that any other appearance modes are turned on, use the
me capability to return them to normal.
Note that the commands to turn on one appearance mode, including so
and mb ... mr, if used while some other appearance modes
are turned on, may combine the two modes on some terminals but may turn off
the mode previously enabled on other terminals. This is because some
terminals do not have a command to set or clear one appearance mode without
changing the others. Programs should not attempt to use appearance modes
in combination except with sa, and when switching from one single
mode to another should always turn off the previously enabled mode and then
turn on the new desired mode.
On some old terminals, the so and se commands may be the same
command, which has the effect of turning standout on if it is off, or off
it is on. It is therefore risky for a program to output extra se
commands for good measure. Fortunately, all these terminals are obsolete.
Programs that update displays in which standout-text may be replaced with
non-standout text must check for the xs flag. In a per-character
terminal, this flag says that the only way to remove standout once written is
to clear that portion of the line with the ce string or something
even more powerful (see Clearing); just writing new characters at those
screen positions will not change the modes in effect there. In a magic
cookie terminal, xs says that the only way to remove a cookie is to
clear a portion of the line that includes the cookie; writing a different
cookie at the same position does not work.
Such programs must also check for the xt flag, which means that the
terminal is a Teleray 1061. On this terminal it is impossible to position
the cursor at the front of a magic cookie, so the only two ways to remove a
cookie are (1) to delete the line it is on or (2) to position the cursor at
least one character before it (possibly on a previous line) and output the
se string, which on these terminals finds and removes the next
so magic cookie on the screen. (It may also be possible to remove a
cookie which is not at the beginning of a line by clearing that line.) The
xt capability also has implications for the use of tab characters,
but in that regard it is obsolete (See Cursor Motion).
so
se
sg
ms
xs
xt
se is a command to delete
the next magic cookie following the cursor. See discussion above.
mb
md
mh
mk
mp
mr
me
mb ... mr is present.
as
ae
sa
sa capability, even among those that do have various
appearance modes.
The nine parameters are, in order, standout, underline, reverse, blink, half-bright, double-bright, blank, protect, alt char set.
Underlining on most terminals is a kind of appearance mode, much like standout mode. Therefore, it may be implemented using magic cookies or as a flag in the terminal whose current state affects each character that is output. See Standout, for a full explanation.
The ug capability is a numeric capability whose presence indicates
that the terminal uses magic cookies for underlining. Its value is the
number of character positions that a magic cookie for underlining occupies;
it is used for underlining just as sg is used for standout. Aside
from the simplest applications, it is impossible to use underlining
correctly without paying attention to the value of ug.
us
ue
ug
ms
There are two other, older ways of doing underlining: there can be a
command to underline a single character, or the output of _, the
ASCII underscore character, as an overstrike could cause a character to be
underlined. New programs need not bother to handle these capabilities
unless the author cares strongly about the obscure terminals which support
them. However, terminal descriptions should provide these capabilities
when appropriate.
uc
ul
_); some terminals can do
this even though they do not support overstriking in general. An
implication of this flag is that when outputting new text to overwrite
old text, underscore characters must be treated specially lest they
underline the old text instead.
Some terminals have the ability to make the cursor invisible, or to enhance it. Enhancing the cursor is often done by programs that plan to use the cursor to indicate to the user a position of interest that may be anywhere on the screen--for example, the Emacs editor enhances the cursor on entry. Such programs should always restore the cursor to normal on exit.
vs
vi
ve
If you define either vs or vi, you must also define ve.
Here we describe commands to make the terminal ask for the user to pay attention to it.
bl
vb
Many terminals have arrow and function keys that transmit specific character sequences to the computer. Since the precise sequences used depend on the terminal, termcap defines capabilities used to say what the sequences are. Unlike most termcap string-valued capabilities, these are not strings of commands to be sent to the terminal, rather strings that are received from the terminal.
Programs that expect to use keypad keys should check, initially, for a
ks capability and send it, to make the keypad actually transmit.
Such programs should also send the ke string when exiting.
ks
ke
ks is.
kl
kr
ku
kd
kh
K1 ... K5
kh key.
k0
k1 ... k9
kn
l0 ... l9
k0 ... l9. These
capabilities should be left undefined if the labels are f0 or
f10 and f1 ... f9.
kH
kb
ka
kt
kC
kD
kL
kM
kE
kS
kI
kA
kN
kP
kF
kR
kT
ko
kH ... kT keys. The string contains a list of
two-character termcap capability names, separated by commas. The
meaning is that for each capability name listed, the terminal has a
key which sends the string which is the value of that capability. For
example, the value :ko=cl,ll,sf,sr: says that the terminal has
four function keys which mean "clear screen", "home down",
"scroll forward" and "scroll reverse".
A Meta key is a key on the keyboard that modifies each character you type by controlling the 0200 bit. This bit is on if and only if the Meta key is held down when the character is typed. Characters typed using the Meta key are called Meta characters. Emacs uses Meta characters as editing commands.
km
mm
mo
If the terminal has km but does not have mm and mo, it
means that the Meta key always functions. If it has mm and
mo, it means that the Meta key can be turned on or off. Send the
mm string to turn it on, and the mo string to turn it off.
I do not know why one would ever not want it to be on.
ti
te
ti string.
Programs that output the ti string on entry should output this
string when they exit.
is
if
is
and if are not both used.
i1
i3
i1 string (if defined) is output before is
or if, and the i3 string (if defined) is output after.
The reason for having three separate initialization strings is to make
it easier to define a group of related terminal types with slightly
different initializations. Define two or three of the strings in the
basic type; then the other types can override one or two of the
strings.
rs
is string (or other commands
with the same effects) and more. What would go in the rs
string but not in the is string are annoying or slow commands
to bring the terminal back from strange modes that nobody would
normally use.
it
ct
st
NF
There are two terminal capabilities that exist just to explain the proper
way to obey the padding specifications in all the command string
capabilities. One, pc, must be obeyed by all termcap-using
programs.
pb
pc
pc is not provided, use null characters. Every
program that uses termcap must look up this capability and use it to
set the variable PC that is used by tputs.
See Padding.
Some termcap capabilities exist just to specify the amount of padding that the kernel should give to cursor motion commands used in ordinary sequential output.
dC
dN
dB
dF
dT
In some systems, the kernel uses the above capabilities; in other systems,
the kernel uses the paddings specified in the string capabilities
cr, sf, le, ff and ta. Descriptions of
terminals which require such padding should contain the dC ...
dT capabilities and also specify the appropriate padding in the
corresponding string capabilities. Since no modern terminals require
padding for ordinary sequential output, you probably won't need to do
either of these things.
A status line is a line on the terminal that is not used for ordinary display output but instead used for a special message. The intended use is for a continuously updated description of what the user's program is doing, and that is where the name "status line" comes from, but in fact it could be used for anything. The distinguishing characteristic of a status line is that ordinary output to the terminal does not affect it; it changes only if the special status line commands of this section are used.
hs
ts and fs capabilities.
ts
fs string.
fs
es
ch
if there is a ch capability, enter and leave standout mode, and
so on.
ds
ws
Note that the value of ws is sometimes as small as 8.
Some terminals have commands for moving the cursor vertically by half-lines, useful for outputting subscripts and superscripts. Mostly it is hardcopy terminals that have such features.
hu
hd
Some terminals have attached hardcopy printer ports. They may be able to copy the screen contents to the printer; they may also be able to redirect output to the printer. Termcap does not have anything to tell the program whether the redirected output appears also on the screen; it does on some terminals but not all.
ps
po
pf
po is.
pO
pf string if there is one. The number n should not be
more than 255.
One use of this capability is to send non-text byte sequences (such as bit-maps) to the printer.
Most terminals with printers do not support all of ps, po and
pO; any one or two of them may be supported. To make a program that
can send output to all kinds of printers, it is necessary to check for all
three of these capabilities, choose the most convenient of the ones that
are provided, and use it in its own appropriate fashion.
Here are all the terminal capability names in alphabetical order with a brief description of each. For cross references to their definitions, see the index of capability names (see Cap Index).
ae
al
AL
am
as
bc
le capability.
bl
bs
bt
bw
le at left margin wraps to end of previous line.
CC
cd
ce
ch
cl
cm
CM
co
cr
cs
cS
ct
cv
da
db
dB
dc
dC
DC
dF
dl
DL
dm
dN
do
DO
ds
dT
ec
ed
ei
eo
es
ff
fs
gn
hc
hd
ho
hs
hu
hz
~ as output.
i1
i3
ic
IC
if
im
in
ip
is
it
k0
k1 ... k9
K1 ... K5
ka
kA
kb
kC
kd
kD
ke
kE
kF
kh
kH
kI
kl
kL
km
kM
kn
kN
ko
kP
kr
kR
ks
kS
kt
kT
ku
l0
l1 ... l9
le
LE
li
ll
lm
LP
mb
md
me
mh
mi
mk
mm
mo
mp
mr
ms
nc
nd
NF
nl
do and sf capabilities.
ns
nw
os
pb
pc
pf
po
pO
ps
rc
RI
rp
rs
sa
sc
se
sf
SF
sg
so
sr
SR
st
ta
te
ti
ts
uc
ue
ug
ul
up
UP
us
vb
ve
vi
vs
wi
ws
xb
xn
xs
xt
BC: tgoto
ospeed: Output Padding
PC: Output Padding
tgetent: Find
tgetflag: Interrogate
tgetnum: Interrogate
tgetstr: Interrogate
tgoto: tgoto
tparam: tparam
tputs: Output Padding
UP: tgoto
ae: Standout
AL: Insdel Line
al: Insdel Line
am: Wrapping
as: Standout
bc: Cursor Motion
bl: Bell
bs: Cursor Motion
bt: Cursor Motion
bw: Cursor Motion
CC: Basic
cd: Clearing
ce: Clearing
ch: Cursor Motion
cl: Clearing
cm: Cursor Motion
CM: Cursor Motion
co: Screen Size
cr: Cursor Motion
cS: Scrolling
cs: Scrolling
ct: Initialization
cv: Cursor Motion
da: Scrolling
dB: Pad Specs
db: Scrolling
dC: Pad Specs
DC: Insdel Char
dc: Insdel Char
dF: Pad Specs
dl: Insdel Line
DL: Insdel Line
dm: Insdel Char
dN: Pad Specs
do: Cursor Motion
DO: Cursor Motion
ds: Status Line
dT: Pad Specs
ec: Clearing
ed: Insdel Char
ei: Insdel Char
eo: Basic
es: Status Line
ff: Cursor Motion
fs: Status Line
gn: Basic
hc: Basic
hd: Half-Line
ho: Cursor Motion
hs: Status Line
hu: Half-Line
hz: Basic
i1: Initialization
i3: Initialization
ic: Insdel Char
IC: Insdel Char
if: Initialization
im: Insdel Char
in: Insdel Char
ip: Insdel Char
is: Initialization
it: Initialization
K1...K5: Keypad
k1...k9: Keypad
kA...kT: Keypad
ka...ku: Keypad
km: Meta Key
l0...l9: Keypad
le: Cursor Motion
LE: Cursor Motion
li: Screen Size
ll: Cursor Motion
lm: Scrolling
LP: Wrapping
mb: Standout
md: Standout
me: Standout
mh: Standout
mi: Insdel Char
mk: Standout
mm: Meta Key
mo: Meta Key
mp: Standout
mr: Standout
ms: Underlining, Standout
nc: Cursor Motion
nd: Cursor Motion
NF: Initialization
nl: Cursor Motion
ns: Scrolling
nw: Cursor Motion
os: Basic
pb: Pad Specs
pc: Pad Specs
pf: Printer
po: Printer
pO: Printer
ps: Printer
rc: Cursor Motion
RI: Cursor Motion
rp: Basic
rs: Initialization
sa: Standout
sc: Cursor Motion
se: Standout
sf: Scrolling
SF: Scrolling
sg: Standout
so: Standout
sr: Scrolling
SR: Scrolling
st: Initialization
ta: Cursor Motion
te: Initialization
ti: Initialization
ts: Status Line
uc: Underlining
ue: Underlining
ug: Underlining
ul: Underlining
UP: Cursor Motion
up: Cursor Motion
us: Underlining
vb: Bell
ve: Cursor Visibility
vi: Cursor Visibility
vs: Cursor Visibility
wi: Windows
ws: Status Line
xb: Basic
xn: Wrapping
xs: Standout
xt: Cursor Motion, Standout