termcap.texi

linux下bash的源码

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.

@node Describe Padding, Output Padding, Not Enough, Padding
@subsection Specifying Padding in a Terminal Description

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 (@samp{*}) following the padding time says that the time
should be multiplied by the number of screen lines affected by the command.

@example
:al=1.3*\E[L:
@end example

@noindent
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
@samp{@key{ESC} [ L}.

The padding time specified in this way tells @code{tputs} how many pad
characters to output.  @xref{Output Padding}.

Two special capability values affect padding for all commands.  These are
the @samp{pc} and @samp{pb}.  The variable @samp{pc} specifies the
character to pad with, and @samp{pb} the speed below which no padding is
needed.  The defaults for these variables, a null character and 0,
are correct for most terminals.  @xref{Pad Specs}.

@node Output Padding,  , Describe Padding, Padding
@subsection Performing Padding with @code{tputs}
@cindex line speed

@findex tputs
Use the termcap function @code{tputs} to output a string containing an
optional padding spec of the form described above (@pxref{Describe
Padding}).  The function @code{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:

@example
char PC;
short ospeed;

int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ());
@end example

Here @var{string} is the string (including padding spec) to be output;
@var{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
@samp{*}.  Finally, @var{outfun} is a function (such as @code{fputchar})
that is called to output each character.  When actually called,
@var{outfun} should expect one argument, a character.

@vindex ospeed
@vindex PC
The operation of @code{tputs} is controlled by two global variables,
@code{ospeed} and @code{PC}.  The value of @code{ospeed} is supposed to be
the terminal output speed, encoded as in the @code{ioctl} system call which
gets the speed information.  This is needed to compute the number of
padding characters.  The value of @code{PC} is the character used for
padding.

You are responsible for storing suitable values into these variables before
using @code{tputs}.  The value stored into the @code{PC} variable should be
taken from the @samp{pc} capability in the terminal description (@pxref{Pad
Specs}).  Store zero in @code{PC} if there is no @samp{pc}
capability.@refill

The argument @var{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
@samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end
of the screen), @var{nlines} should be the screen height minus the current
vertical position (origin 0).  For multiple insert and scroll commands such
as @samp{AL} (insert multiple lines), that same value for @var{nlines} is
correct; the number of lines being inserted is @i{not} correct.@refill

If a ``scroll window'' feature is used to reduce the number of lines
affected by a command, the value of @var{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.
@xref{Scrolling}.

Commands such as @samp{ic} and @samp{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 @var{nlines} should really be the number of columns affected.
However, the definition of termcap clearly says that @var{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 @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings,
there is no reason for them to use @samp{*}, but some of them do.  These
should be corrected by deleting the @samp{*}.  If, some day, such entries
have disappeared, it may be possible to change to a more useful convention
for the @var{nlines} argument for these operations without breaking any
programs.

@node Parameters,  , Padding, Library
@section Filling In Parameters
@cindex parameters

Some terminal control strings require numeric @dfn{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 @samp{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 @samp{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 @samp{%}.  (This is the same idea as
@code{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 @code{tparam} or
@code{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 @code{tputs};
@pxref{Padding}).

@menu
* Encode Parameters::  The language for encoding parameters.
* Using Parameters::  Outputting a string command with parameters.
@end menu

@node Encode Parameters, Using Parameters,  , Parameters
@subsection Describing the Encoding
@cindex %

A terminal command string that requires parameters contains special
character sequences starting with @samp{%} to say how to encode the
parameters.  These sequences control the actions of @code{tparam} and
@code{tgoto}.

The parameters values passed to @code{tparam} or @code{tgoto} are
considered to form a vector.  A pointer into this vector determines
the next parameter to be processed.  Some of the @samp{%}-sequences
encode one parameter and advance the pointer to the next parameter.
Other @samp{%}-sequences alter the pointer or alter the parameter
values without generating output.

For example, the @samp{cm} string for a standard ANSI terminal is written
as @samp{\E[%i%d;%dH}.  (@samp{\E} stands for @key{ESC}.)  @samp{cm} by
convention always requires two parameters, the vertical and horizontal goal
positions, so this string specifies the encoding of two parameters.  Here
@samp{%i} increments the two values supplied, and each @samp{%d} encodes
one of the values in decimal.  If the cursor position values 20,58 are
encoded with this string, the result is @samp{\E[21;59H}.

First, here are the @samp{%}-sequences that generate output.  Except for
@samp{%%}, each of them encodes one parameter and advances the pointer
to the following parameter.

@table @samp
@item %%
Output a single @samp{%}.  This is the only way to represent a literal
@samp{%} in a terminal command with parameters.  @samp{%%} does not
use up a parameter.

@item %d
As in @code{printf}, output the next parameter in decimal.

@item %2
Like @samp{%02d} in @code{printf}: output the next parameter in
decimal, and always use at least two digits.

@item %3
Like @samp{%03d} in @code{printf}: output the next parameter in
decimal, and always use at least three digits.  Note that @samp{%4}
and so on are @emph{not} defined.

@item %.
Output the next parameter as a single character whose ASCII code is
the parameter value.  Like @samp{%c} in @code{printf}.

@item %+@var{char}
Add the next parameter to the character @var{char}, and output the
resulting character.  For example, @samp{%+ } represents 0 as a space,
1 as @samp{!}, etc.
@end table

The following @samp{%}-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 @samp{%i}, @samp{%r} and @samp{%>} are
defined in standard Unix termcap.  The others are GNU extensions.@refill

@table @samp
@item %i
Increment the next two parameters.  This is used for terminals that
expect cursor positions in origin 1.  For example, @samp{%i%d,%d} would
output two parameters with @samp{1} for 0, @samp{2} for 1, etc.

@item %r
Interchange the next two parameters.  This is used for terminals whose
cursor positioning command expects the horizontal position first.

@item %s
Skip the next parameter.  Do not output anything.

@item %b
Back up one parameter.  The last parameter used will become once again
the next parameter to be output, and the next output command will use
it.  Using @samp{%b} more than once, you can back up any number of
parameters, and you can refer to each parameter any number of times.

@item %>@var{c1}@var{c2}
Conditionally increment the next parameter.  Here @var{c1} and
@var{c2} are characters which stand for their ASCII codes as numbers.
If the next parameter is greater than the ASCII code of @var{c1}, the
ASCII code of @var{c2} is added to it.@refill

@item %a @var{op} @var{type} @var{pos}
Perform arithmetic on the next parameter, do not use it up, and do not
output anything.  Here @var{op} specifies the arithmetic operation,
while @var{type} and @var{pos} together specify the other operand.

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 @var{op} says what kind of arithmetic operation to
perform.  It can be any of these characters:

@table @samp
@item =
assign a value to the next parameter, ignoring its old value.
The new value comes from the other operand.

@item +
add the other operand to the next parameter.

@item -
subtract the other operand from the next parameter.

@item *
multiply the next parameter by the other operand.

@item /
divide the next parameter by the other operand.
@end table

The ``other operand'' may be another parameter's value or a constant;
the character @var{type} says which.  It can be:

@table @samp
@item p
Use another parameter.  The character @var{pos} says which
parameter to use.  Subtract 64 from its ASCII code to get the
position of the desired parameter relative to this one.  Thus,
the character @samp{A} as @var{pos} means the parameter after the
next one; the character @samp{?} means the parameter before the
next one.

@item c
Use a constant value.  The character @var{pos} specifies the
value of the constant.  The 0200 bit is cleared out, so that 0200
can be used to represent zero.
@end table
@end table

The following @samp{%}-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.  @samp{%m} is a GNU extension; the others are defined in
standard Unix termcap.

@table @samp
@item %n
Exclusive-or the next parameter with 0140, and likewise the parameter
after next.

@item %m
Complement all the bits of the next parameter and the parameter after next.

@item %B
Encode the next parameter in BCD.  It alters the value of the
parameter by adding six times the quotient of the parameter by ten.
Here is a C statement that shows how the new value is computed:

@example
@var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10;
@end example

@item %D
Transform the next parameter as needed by Delta Data terminals.
This involves subtracting twice the remainder of the parameter by 16.