termcap.texinfo

早期freebsd实现

the capability is present, @code{tgetnum} returns the numeric value
(which is nonnegative).  If the capability is not mentioned in the
terminal description, @code{tgetnum} returns @minus{}1.

@item tgetflag
Use @code{tgetflag} to get a boolean value.  If the capability
@var{name} is present in the terminal description, @code{tgetflag}
returns 1; otherwise, it returns 0.

@item tgetstr
Use @code{tgetstr} to get a string value.  It returns a pointer to a
string which is the capability value, or a null pointer if the
capability is not present in the terminal description.

There are two ways @code{tgetstr} can find space to store the string value:

@itemize @bullet
@item
You can ask @code{tgetstr} to allocate the space.  Pass a null
pointer for the argument @var{area}, and @code{tgetstr} will use
@code{malloc} to allocate storage big enough for the value.
Termcap will never free this storage or refer to it again; you
should free it when you are finished with it.

This method is more robust, since there is no need to guess how
much space is needed.  But it is supported only by the GNU
termcap library.

@item
You can provide the space.  Provide for the argument @var{area} the
address of a pointer variable of type @code{char *}.  Before calling
@code{tgetstr}, initialize the variable to point at available space.
Then @code{tgetstr} will store the string value in that space and will
increment the pointer variable to point after the space that has been
used.  You can use the same pointer variable for many calls to
@code{tgetstr}.

There is no way to determine how much space is needed for a single
string, and no way for you to prevent or handle overflow of the area
you have provided.  However, you can be sure that the total size of
all the string values you will obtain from the terminal description is
no greater than the size of the description (unless you get the same
capability twice).  You can determine that size with @code{strlen} on
the buffer you provided to @code{tgetent}.  See below for an example.

Providing the space yourself is the only method supported by the Unix
version of termcap.
@end itemize
@end table

Note that you do not have to specify a terminal type or terminal
description for the interrogation functions.  They automatically use the
description found by the most recent call to @code{tgetent}.

Here is an example of interrogating a terminal description for various
capabilities, with conditionals to select between the Unix and GNU methods
of providing buffer space.

@example
char *tgetstr ();

char *cl_string, *cm_string;
int height;
int width;
int auto_wrap;

char PC;   /* For tputs.  */
char *BC;  /* For tgoto.  */
char *UP;

interrogate_terminal ()
@{
#ifdef UNIX
  /* Here we assume that an explicit term_buffer
     was provided to tgetent.  */
  char *buffer
    = (char *) malloc (strlen (term_buffer));
#define BUFFADDR &buffer
#else
#define BUFFADDR 0
#endif

  char *temp;

  /* Extract information we will use.  */
  cl_string = tgetstr ("cl", BUFFADDR);
  cm_string = tgetstr ("cm", BUFFADDR);
  auto_wrap = tgetflag ("am");
  height = tgetnum ("li");
  width = tgetnum ("co");

  /* Extract information that termcap functions use.  */
  temp = tgetstr ("pc", BUFFADDR);
  PC = temp ? *temp : 0;
  BC = tgetstr ("le", BUFFADDR);
  UP = tgetstr ("up", BUFFADDR);
@}
@end example

@noindent
@xref{Padding}, for information on the variable @code{PC}.  @xref{Using
Parameters}, for information on @code{UP} and @code{BC}.

@node Initialize, Padding, Interrogate, Library
@section Initialization for Use of Termcap
@cindex terminal flags (kernel)

Before starting to output commands to a terminal using termcap,
an application program should do two things:

@itemize @bullet
@item
Initialize various global variables which termcap library output
functions refer to.  These include @code{PC} and @code{ospeed} for
padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for
cursor motion (@pxref{tgoto}).@refill

@item
Tell the kernel to turn off alteration and padding of horizontal-tab
characters sent to the terminal.
@end itemize

To turn off output processing in Berkeley Unix you would use @code{ioctl}
with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear
the bits @code{ANYDELAY} using @code{TIOCSETN}.  In POSIX or System V, you
must clear the bit named @code{OPOST}.  Refer to the system documentation
for details.@refill

If you do not set the terminal flags properly, some older terminals will
not work.  This is because their commands may contain the characters that
normally signify newline, carriage return and horizontal tab---characters
which the kernel thinks it ought to modify before output.

When you change the kernel's terminal flags, you must arrange to restore
them to their normal state when your program exits.  This implies that the
program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT}
and restore the old terminal flags before actually terminating.

Modern terminals' commands do not use these special characters, so if you
do not care about problems with old terminals, you can leave the kernel's
terminal flags unaltered.

@node Padding, Parameters, Initialize, Library
@section Padding
@cindex padding

@dfn{Padding} means outputting null characters following a terminal display
command that takes a long time to execute.  The terminal description says
which commands require padding and how much; the function @code{tputs},
described below, outputs a terminal command while extracting from it the
padding information, and then outputs the padding that is necessary.

@menu
* Why Pad::          Explanation of padding.
* Describe Padding:: The data base says how much padding a terminal needs.
* Output Padding::   Using @code{tputs} to output the needed padding.
@end menu

@node Why Pad, Describe Padding, Padding, Padding
@subsection Why Pad, and How

Most types of terminal have commands that take longer to execute than they
do to send over a high-speed line.  For example, clearing the screen may
take 20msec once the entire command is received.  During that time, on a
9600 bps line, the terminal could receive about 20 additional output
characters while still busy clearing the screen.  Every terminal has a
certain amount of buffering capacity to remember output characters that
cannot be processed yet, but too many slow commands in a row can cause the
buffer to fill up.  Then any additional output that cannot be processed
immediately will be lost.

To avoid this problem, we normally follow each display command with enough
useless charaters (usually null characters) to fill up the time that the
display command needs to execute.  This does the job if the terminal throws
away null characters without using up space in the buffer (which most
terminals do).  If enough padding is used, no output can ever be lost.  The
right amount of padding avoids loss of output without slowing down
operation, since the time used to transmit padding is time that nothing
else could be done.

The number of padding characters needed for an operation depends on the
line speed.  In fact, it is proportional to the line speed.  A 9600 baud
line transmits about one character per msec, so the clear screen command in
the example above would need about 20 characters of padding.  At 1200 baud,
however, only about 3 characters of padding are needed to fill up 20msec.

@node Describe Padding, Output Padding, Why Pad, 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 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