termcap.texinfo

早期freebsd实现

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

@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, 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:

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

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