⟦872fd1693⟧

TextFile

Info file: termcap, -*-Text-*-
produced by texinfo-format-buffer
from file: termcap.texinfo

This file documents the termcap library of the GNU system.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.

▶1f◀
File: termcap Node: Basic, Prev: Capabilities, Up: Capabilities, Next: Screen Size

Basic Characteristics
=====================

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'
Flag whose presence means that the terminal can overstrike. This
means that outputting a graphic character does not erase whatever was
present in the same character position before. The terminals that can
overstrike include printing terminals, storage tubes (all obsolete
nowadays), and many bit-map displays.

`eo'
Flag whose presence means that outputting a space can erase an
overstrike. If this is not present and overstriking is supported,
output of a space has no effect except to move the cursor.

`gn'
Flag whose presence means that this terminal type is a generic type
which does not really describe any particular terminal. Generic types
are intended for use as the default type assigned when the user
connects to the system, with the intention that the user should
specify what type he really has. One example of a generic type
is the type `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'
Flag whose presence means this is a hardcopy terminal.

`rp'
String of commands to output a graphic character C, repeated N
times. The first parameter value is the ASCII code for the desired
character, and the second parameter is the number of times to repeat the
character. Often this command requires padding proportional to the
number of times the character is repeated. This effect can be had by
using parameter arithmetic with `%'-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'
Flag whose presence means that the ASCII character `~' 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'
String whose presence means the terminal has a settable command
character. The value of the string is the default command character
(which is usually ESC).

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'
Flag whose presence identifies Superbee terminals which are unable to
transmit the characters ESC and `Control-C'. Programs which
support this flag are supposed to check the input for the code sequences
sent by the F1 and F2 keys, and pretend that ESC
or `Control-C' (respectively) had been read. But this flag is
obsolete, and not worth supporting.

▶1f◀
File: termcap Node: Screen Size, Prev: Basic, Up: Capabilities, Next: Cursor Motion

Screen Size
===========

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'
Numeric value, the width of the screen in character positions. Even
hardcopy terminals normally have a `co' capability.

`li'
Numeric value, the height of the screen in lines.

▶1f◀
File: termcap Node: Cursor Motion, Prev: Screen Size, Up: Capabilities, Next: Wrapping

Cursor Motion
=============

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. *Note 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'
String of commands to position the cursor at line L, column C.
Both parameters are origin-zero, and are defined relative to the
screen, not relative to display memory.

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'
String of commands to move the cursor to the upper left corner of the
screen (this position is called the "home position"). In
terminals where the upper left corner of the screen is not the same as
the beginning of display memory, this command must go to the upper
left corner of the screen, not the beginning of display memory.

Every display terminal supports this capability, and many application
programs refuse to operate if the `ho' capability is missing.

`ll'
String of commands to move the cursor to the lower left corner of the
screen. On some terminals, moving up from home position does this,
but programs should never assume that will work. Just output the
`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'
String of commands to move the cursor to the beginning of the line it
is on. If this capability is not specified, many programs assume
they can use the ASCII carriage return character for this.

`le'
String of commands to move the cursor left one column. Unless the
`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'
String of commands to move the cursor right one column. The effect is
undefined if the cursor is at the right margin; do not use this
command there, not even if `am' is present.

`up'
String of commands to move the cursor vertically up one line. The
effect of sending this string when on the top line is undefined;
programs should never use it that way.

`do'
String of commands to move the cursor vertically down one line. The
effect of sending this string when on the bottom line is undefined;
programs should never use it that way.

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 (*Note Initialize::).

`bw'
Flag whose presence says that `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'
String of commands to move the cursor to start of next line, possibly
clearing rest of line (following the cursor) before moving.

`DO', `UP', `LE', `RI'
Strings of commands to move the cursor N lines down vertically,
up vertically, or N columns left or right. Do not attempt to
move past any edge of the screen with these commands; the effect of
trying that is undefined. Only a few terminal descriptions provide
these commands, and most programs do not use them.

`CM'
String of commands to position the cursor at line L, column
C, relative to display memory. Both parameters are origin-zero.
This capability is present only in terminals where there is a
difference between screen-relative and memory-relative addressing, and
not even in all such terminals.

`ch'
String of commands to position the cursor at column C in the
same line it is on. This is a special case of `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'
String of commands to position the cursor at line L in the same
column. This is a special case of `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'
String of commands to make the terminal save the current cursor
position. Only the last saved position can be used. If this
capability is present, `rc' should be provided also. Most
terminals have neither.

`rc'
String of commands to make the terminal restore the last saved cursor
position. If this capability is present, `sc' should be provided
also. Most terminals have neither.

`ff'
String of commands to advance to the next page, for a hardcopy
terminal.

`ta'
String of commands to move the cursor right to the next hardware tab
stop column. Missing if the terminal does not have any kind of
hardware tabs. Do not send this command if the kernel's terminal
modes say that the kernel is expanding tabs into spaces.

`bt'
String of commands to move the cursor left to the previous hardware
tab stop column. Missing if the terminal has no such ability; many
terminals do not. Do not send this command if the kernel's terminal
modes say that the kernel is expanding tabs into spaces.

The following obsolete capabilities should be included in terminal
descriptions when appropriate, but should not be looked at by new programs.

`nc'
Flag whose presence means the terminal does not support the ASCII
carriage return character as `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'
Flag whose presence means that the ASCII tab character may not be used
for cursor motion. This flag exists because old programs assume, when
the `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 (*Note 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'
Very obsolete alternative name for the `le' capability.

`bs'
Flag whose presence means that the ASCII character backspace may be
used to move the cursor left. Obsolete; look at `le' instead.

`nl'
Obsolete capability which is a string that can either be used to move
the cursor down or to scroll. The same string must scroll when used
on the bottom line and move the cursor when used on any other line.
New programs should use `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.

▶1f◀
File: termcap Node: Wrapping, Prev: Cursor Motion, Up: Capabilities, Next: Scrolling

Wrapping
========

"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'
Flag whose presence means that writing a character in the last column
causes the cursor to wrap to the beginning of the next line.

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 (*Note 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'
Flag whose presence means that the cursor wraps in a strange way. At
least two distinct kinds of strange behavior are known; the termcap
data base does not contain anything to distinguish the two.

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.

▶1f◀
File: termcap Node: Scrolling, Prev: Wrapping, Up: Capabilities, Next: Windows

Scrolling
=========

"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'
String of commands to scroll the screen one line up, assuming it is
output with the cursor at the beginning of the bottom line.

`sr'
String of commands to scroll the screen one line down, assuming it is
output with the cursor at the beginning of the top line.

`SF'
String of commands to scroll the screen N lines up, assuming it
is output with the cursor at the beginning of the bottom line.

`SR'
String of commands to scroll the screen N line down, assuming it
is output with the cursor at the beginning of the top line.

`cs'
String of commands to set the scroll region. This command takes two
parameters, START and END, which are the line numbers
(origin-zero) of the first line to include in the scroll region and of
the last line to include in it. When a scroll region is set,
scrolling is limited to the specified range of lines; lines outside
the range are not affected by scroll commands.

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'
String of commands to set the scroll region using parameters in
different form. The effect is the same as if `cs' were used.
Four parameters are required:

1. Total number of lines on the screen.
2. Number of lines above desired scroll region.
3. Number of lines below (outside of) desired scroll region.
4. Total number of lines on the screen, the same as the first parameter.

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'
Flag which means that the terminal does not normally scroll for
ordinary sequential output. For modern terminals, this means that
outputting a newline in ordinary sequential output with the cursor on
the bottom line wraps to the top line. For some obsolete terminals,
other things may happen.

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'
Flag whose presence means that lines scrolled up off the top of the
screen may come back if scrolling down is done subsequently.

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'
Flag whose presence means that lines scrolled down off the bottom of
the screen may come back if scrolling up is done subsequently.

`lm'
Numeric value, the number of lines of display memory that the terminal
has. A value of zero means that the terminal has more display memory
than can fit on the screen, but no fixed number of lines. (The number
of lines may depend on the amount of text in each line.)

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. *Note Padding::.

▶1f◀
File: termcap Node: Windows, Prev: Scrolling, Up: Capabilities, Next: Clearing

Windows
=======

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'
String of commands to set the terminal output screen window.
This string requires four parameters, all origin-zero:
1. The first line to include in the window.
2. The last line to include in the window.
3. The first column to include in the window.
4. The last column to include in the window.

Most terminals do not support windows.

▶1f◀
File: termcap Node: Clearing, Prev: Windows, Up: Capabilities, Next: Insdel Line

Clearing Parts of the Screen
============================

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'
String of commands to clear the entire screen and position the cursor
at the upper left corner.

`cd'
String of commands to clear the line the cursor is on, and all the
lines below it, down to the bottom of the screen. This command string
should be used only with the cursor in column zero; their effect is
undefined if the cursor is elsewhere.

`ce'
String of commands to clear from the cursor to the end of the current
line.

`ec'
String of commands to clear N characters, starting with the
character that the cursor is on. This command string is expected to
leave the cursor position unchanged. The parameter N should never
be large enough to reach past the right margin; the effect of such a
large parameter would be undefined.

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'.

▶1f◀
File: termcap Node: Insdel Line, Prev: Clearing, Up: Capabilities, Next: Insdel Char

Insert/Delete Line
==================

"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'
String of commands to insert a blank line before the line the cursor
is on. The existing line, and all lines below it, are moved down.
The last line in the screen (or in the scroll region, if one is set)
disappears and in most circumstances is discarded. It may not be
discarded if the `db' is present (*Note Scrolling::).

The cursor must be at the left margin before this command is used.
This command does not move the cursor.

`dl'
String of commands to delete the line the cursor is on. The following
lines move up, and a blank line appears at the bottom of the screen
(or bottom of the scroll region). If the terminal has the `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'
String of commands to insert N blank lines before the line that
the cursor is on. It is like `al' repeated N times, except
that it is as fast as one `al'.

`DL'
String of commands to delete N lines starting with the line that
the cursor is on. It is like `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.
*Note 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. *Note 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'.

▶1f◀
File: termcap Node: Insdel Char, Prev: Insdel Line, Up: Capabilities, Next: Standout

Insert/Delete Character
=======================

"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'
String of commands to enter insert mode.

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'
String of commands to leave insert mode. This capability must be
present if `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'
String of commands to insert one character position at the cursor.
The cursor does not move.

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'
String of commands to output following an inserted graphic character
in insert mode. Often it is used just for a padding spec, when padding
is needed after an inserted character (*Note Padding::).

`IC'
String of commands to insert N character positions at and after
the cursor. It has the same effect as repeating the `ic' string
and a space, N times.

If `IC' is provided, application programs may use it without first
entering insert mode.

`mi'
Flag whose presence means it is safe to move the cursor while in insert
mode and assume the terminal remains in insert mode.

`in'
Flag whose presence means that the terminal distinguishes between
character positions in which space characters have been output and
positions which have been cleared.

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:

1. If an `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.

2. Output the `im' string, if there is one, unless the terminal is
already in insert mode.

3. Repeat steps 4 through 6, N times.

4. Output the `ic' string if any.

5. Output a space.

6. Output the `ip' string if any.

7. Output the `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:

1. If an `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.

2. Output the `im' string, if there is one, unless the terminal is
already in insert mode.

3. For each character to be output, repeat steps 4 through 6.

4. Output the `ic' string if any.

5. Output the next graphic character.

6. Output the `ip' string if any.

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'
String of commands to delete one character position at the cursor. If
`dc' is not present, the terminal cannot delete characters.

`DC'
String of commands to delete N characters starting at the cursor.
It has the same effect as repeating the `dc' string N times.
Any terminal description that has `DC' also has `dc'.

`dm'
String of commands to enter delete mode. If not present, there is no
delete mode, and `dc' can be used at any time (assuming there is
a `dc').

`ed'
String of commands to exit delete mode. This must be present if
`dm' is.

To delete N character positions, position the cursor and follow these
steps:

1. If the `DC' string is present, output it with parameter N
and you are finished. Otherwise, follow the remaining steps.

2. Output the `dm' string, unless you know the terminal is already
in delete mode.

3. Output the `dc' string N times.

4. Output the `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.

▶1f◀
File: termcap Node: Standout, Prev: Insdel Char, Up: Capabilities, Next: Underlining

Standout and Appearance Modes
=============================

"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 (*Note 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 (*Note Cursor Motion::).

`so'
String of commands to enter standout mode.

`se'
String of commands to leave standout mode.

`sg'
Numeric capability, the width on the screen of the magic cookie. This
capability is absent in terminals that record appearance modes
character by character.

`ms'
Flag whose presence means that it is safe to move the cursor while the
appearance modes are not in the normal state. If this flag is absent,
programs should always reset the appearance modes to normal before
moving the cursor.

`xs'
Flag whose presence means that the only way to reset appearance modes
already on the screen is to clear to end of line. On a per-character
terminal, you must clear the area where the modes are set. On a magic
cookie terminal, you must clear an area containing the cookie.
See the discussion above.

`xt'
Flag whose presence means that the cursor cannot be positioned right
in front of a magic cookie, and that `se' is a command to delete
the next magic cookie following the cursor. See discussion above.

`mb'
String of commands to enter blinking mode.

`md'
String of commands to enter double-bright mode.

`mh'
String of commands to enter half-bright mode.

`mk'
String of commands to enter invisible mode.

`mp'
String of commands to enter protected mode.

`mr'
String of commands to enter reverse-video mode.

`me'
String of commands to turn off all appearance modes, including
standout mode and underline mode. On some terminals it also turns off
alternate character set mode; on others, it may not. This capability
must be present if any of `mb' ... `mr' is present.

`as'
String of commands to turn on alternate character set mode. This mode
assigns some or all graphic characters an alternate picture on the
screen. There is no standard as to what the alternate pictures look
like.

`ae'
String of commands to turn off alternate character set mode.

`sa'
String of commands to turn on an arbitrary combination of appearance
modes. It accepts 9 parameters, each of which controls a particular
kind of appearance mode. A parameter should be 1 to turn its appearance
mode on, or zero to turn that mode off. Most terminals do not support
the `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.

▶1f◀
File: termcap Node: Underlining, Prev: Standout, Up: Capabilities, Next: Cursor Visibility

Underlining
===========

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. *Note 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'
String of commands to turn on underline mode or to output a magic cookie
to start underlining.

`ue'
String of commands to turn off underline mode or to output a magic
cookie to stop underlining.

`ug'
Width of magic cookie that represents a change of underline mode;
or missing, if the terminal does not use a magic cookie for this.

`ms'
Flag whose presence means that it is safe to move the cursor while the
appearance modes are not in the normal state. Underlining is an
appearance mode. If this flag is absent, programs should always turn
off underlining before moving the cursor.

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'
String of commands to underline the character under the cursor, and
move the cursor right.

`ul'
Flag whose presence means that the terminal can underline by
overstriking an underscore character (`_'); 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.

▶1f◀

DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦872fd1693⟧ TextFile

Derivation

TextFile