termcap.texi

linux下bash的源码

@example
@var{parm} -= 2 * (@var{parm} % 16);
@end example
@end table

@node Using Parameters,  , Encode Parameters, Parameters
@subsection Sending Display Commands with Parameters

The termcap library functions @code{tparam} and @code{tgoto} serve as the
analog of @code{printf} for terminal string parameters.  The newer function
@code{tparam} is a GNU extension, more general but missing from Unix
termcap.  The original parameter-encoding function is @code{tgoto}, which
is preferable for cursor motion.

@menu
* tparam::      The general case, for GNU termcap only.
* tgoto::       The special case of cursor motion.
@end menu

@node tparam, tgoto,  , Using Parameters
@subsubsection @code{tparam}

@findex tparam
The function @code{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 @samp{cm} capability.  Its
ANSI C declaration is as follows:

@smallexample
char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...)
@end smallexample

The arguments are a control string @var{ctlstring} (the value of a terminal
capability, presumably), an output buffer @var{buffer} and @var{size}, and
any number of integer parameters to be encoded.  The effect of
@code{tparam} is to copy the control string into the buffer, encoding
parameters according to the @samp{%} sequences in the control string.

You describe the output buffer by its address, @var{buffer}, and its size
in bytes, @var{size}.  If the buffer is not big enough for the data to be
stored in it, @code{tparam} calls @code{malloc} to get a larger buffer.  In
either case, @code{tparam} returns the address of the buffer it ultimately
uses.  If the value equals @var{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 @var{size} and
@var{buffer}, @code{tparam} always allocates the space with @code{malloc}.

All capabilities that require parameters also have the ability to specify
padding, so you should use @code{tputs} to output the string produced by
@code{tparam}.  @xref{Padding}.  Here is an example.

@example
@{
char *buf;
char buffer[40];

buf = tparam (command, buffer, 40, parm);
tputs (buf, 1, fputchar);
if (buf != buffer)
free (buf);
@}
@end example

If a parameter whose value is zero is encoded with @samp{%.}-style
encoding, the result is a null character, which will confuse @code{tputs}.
This would be a serious problem, but luckily @samp{%.} encoding is used
only by a few old models of terminal, and only for the @samp{cm}
capability.  To solve the problem, use @code{tgoto} rather than
@code{tparam} to encode the @samp{cm} capability.@refill

@node tgoto,  , tparam, Using Parameters
@subsubsection @code{tgoto}

@findex tgoto
The special case of cursor motion is handled by @code{tgoto}.  There
are two reasons why you might choose to use @code{tgoto}:

@itemize @bullet
@item
For Unix compatibility, because Unix termcap does not have @code{tparam}.

@item
For the @samp{cm} capability, since @code{tgoto} has a special feature
to avoid problems with null characters, tabs and newlines on certain old
terminal types that use @samp{%.} encoding for that capability.
@end itemize

Here is how @code{tgoto} might be declared in ANSI C:

@example
char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos})
@end example

There are three arguments, the terminal description's @samp{cm} string and
the two cursor position numbers; @code{tgoto} computes the parametrized
string in an internal static buffer and returns the address of that buffer.
The next time you use @code{tgoto} the same buffer will be reused.

@vindex UP
@vindex BC
Parameters encoded with @samp{%.} encoding can generate null characters,
tabs or newlines.  These might cause trouble: the null character because
@code{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, @code{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), @code{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 @code{BC} and @code{UP}.  These are actual external C
variables with upper case names; they are declared @code{char *}.  It is up
to you to store suitable values in them, normally obtained from the
@samp{le} and @samp{up} terminal capabilities in the terminal description
with @code{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 @code{tgoto} for commands other than @samp{cm} only if
you have stored zero in @code{BC} and @code{UP}.

Note that @code{tgoto} reverses the order of its operands: the horizontal
position comes before the vertical position in the arguments to
@code{tgoto}, even though the vertical position comes before the horizontal
in the parameters of the @samp{cm} string.  If you use @code{tgoto} with a
command such as @samp{AL} that takes one parameter, you must pass the
parameter to @code{tgoto} as the ``vertical position''.@refill

@node Data Base, Capabilities, Library, Top
@chapter The Format of the Data Base

The termcap data base of terminal descriptions is stored in the file
@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.
* Changing::    When changes in the data base take effect.
@end menu

@node Format, Capability Format,  , 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