termcap.texinfo

早期freebsd实现

@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 @dfn{capability names}
and values.  The capability names have standard meanings
(@pxref{Capabilities}) and their values describe the terminal.

@menu
* Format::            Overall format of a terminal description.
* Capability Format:: Format of capabilities within a description.
* Naming::            Naming conventions for terminal types.
* Inheriting::        Inheriting part of a description from
                        a related terminal type.
@end menu

@node Format, Capability Format, Data Base, Data Base
@section Terminal Description Format
@cindex description format

Aside from comments (lines starting with @samp{#}, 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 @samp{\ 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 @samp{: \ newline tab} immediately before any colon.
This allows each sub-line to start with some indentation.  This works
because, after the @samp{\ newline} are ignored, the result is @samp{: tab
:}; the first colon ends the preceding capability and the second colon
starts the next capability.  If you split with @samp{\ newline} alone, you
may not add any indentation after them.

Here is a real example of a terminal description:

@example
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:
@end example

Each terminal description begins with several names for the terminal type.
The names are separated by @samp{|} 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
@samp{vt52} or @samp{aaa-48}.  @xref{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 @samp{cm} for ``cursor motion string'' or @samp{li}
for ``number of display lines''.

@node Capability Format, Naming, Format, Data Base
@section Writing the Capabilities

There are three kinds of capabilities: flags, numbers, and strings.  Each
kind has its own way of being written in the description.  Each defined
capability has by convention a particular kind of value; for example,
@samp{li} always has a numeric value and @samp{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 @samp{#}, and the number, between two colons.  For
example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li}
capability for 48 lines.@refill

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 @samp{=}, and the characters of the value,
between two colons.  For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is
how the cursor motion command for a standard ANSI terminal would be
specified.@refill

Special characters in the string value can be expressed using
@samp{\}-escape sequences as in C; in addition, @samp{\E} stands for
@key{ESC}.  @samp{^} is also a kind of escape character; @samp{^} followed
by @var{char} stands for the control-equivalent of @var{char}.  Thus,
@samp{^a} stands for the character control-a, just like @samp{\001}.
@samp{\} and @samp{^} themselves can be represented as @samp{\\} and
@samp{\^}.@refill

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

The string value will often contain digits at the front to specify padding
(@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode
parameters (@pxref{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 @code{tputs}, @code{tparam} or @code{tgoto}.  By contrast, @samp{\} and
@samp{^} are considered part of the syntax for specifying the characters
in the string.

Let's look at the VT52 example again:

@example
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:
@end example

Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the
flags @samp{bs} and @samp{pt}, and many string-valued capabilities.  Most
of the strings start with @key{ESC} represented as @samp{\E}.  The rest
contain control characters represented using @samp{^}.  The meanings of the
individual capabilities are defined elsewhere (@pxref{Capabilities}).

@node Naming, Inheriting, Capability Format, Data Base
@section Terminal Type Name Conventions
@cindex names of terminal types

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:

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

@cindex wrapping
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 @samp{vt100-am}.  Otherwise you must
use @samp{vt100-nam}.  Plain @samp{vt100} is defined as a synonym for
either @samp{vt100-am} or @samp{vt100-nam} depending on the
preferences of the local site.@refill

The standard suffix @samp{-am} stands for ``automatic margins''.

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

@cindex screen size
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
@samp{aaa-30}, the terminal will be configured to use 30 lines; if you
choose @samp{aaa-48}, 48 lines will be used, and so on.
@end itemize

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

@table @samp
@item -w
Short for ``wide''.  This is a mode that gives the terminal more
columns than usual.  This is normally a user option.

@item -am
``Automatic margins''.  This is an alternate description for use when
the terminal's margin-wrap switch is on; it contains the @samp{am}
flag.  The implication is that normally the switch is off and the
usual description for the terminal says that the switch is off.

@item -nam
``No automatic margins''.  The opposite of @samp{-am}, this names an
alternative description which lacks the @samp{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.

@item -na
``No arrows''.  This terminal description initializes the terminal to
keep its arrow keys in local mode.  This is a user option.

@item -rv
``Reverse video''.  This terminal description causes text output for
normal video to appear as reverse, and text output for reverse video
to come out as normal.  Often this description differs from the usual
one by interchanging the two strings which turn reverse video on and
off.@refill

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

@item -s
``Status''.  Says to enable use of a status line which ordinary output
does not touch (@pxref{Status Line}).

Some terminals have a special line that is used only as a status line.
For these terminals, there is no need for an @samp{-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 @samp{-s} variant type to request
use of a status line.

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

@item -@var{npages}p
Says that the terminal has @var{npages} pages worth of screen memory,
for terminals where this is a hardware option.

@item -unk
Says that description is not for direct use, but only for reference in
@samp{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 @samp{-unk}.
@end table

@node Inheriting,, Naming, Data Base
@section Inheriting from Related Descriptions

@cindex inheritance
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 @samp{tc} capability.  We say that one description
@dfn{refers to} the other, or @dfn{inherits from} the other.

The @samp{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,

@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:
@end example

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

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

The effective terminal description for type @samp{aaa} consists of the text
shown above followed by the text of the description of @samp{aaa-unk}.  The
@samp{tc} capability is handled automatically by @code{tgetent}, which
finds the description thus referenced and combines the two descriptions
(@pxref{Find}).  Therefore, only the implementor of the terminal
descriptions needs to think about using @samp{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 @samp{@@} after the capability
name, as follows:

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

@node Capabilities, Summary, Data Base, Top
@chapter Definitions of the Terminal Capabilities

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 (@pxref{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
@iftex
in italics
@end iftex
@ifinfo
in upper case
@end ifinfo
for each one.  For example, the @samp{rp} capability is a command that
requires two parameters; its definition begins as follows:

@quotation
String of commands to output a graphic character @var{c}, repeated @var{n}
times.
@end quotation

In complex cases or when there are many parameters, they are described