termcap.texi

linux下bash的源码

Here is how you might use the function @code{tgetent}:

@smallexample
#ifdef unix
static char term_buffer[2048];
#else
#define term_buffer 0
#endif

init_terminal_data ()
@{
  char *termtype = getenv ("TERM");
  int success;

  if (termtype == 0)
    fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");

  success = tgetent (term_buffer, termtype);
  if (success < 0)
    fatal ("Could not access the termcap data base.\n");
  if (success == 0)
    fatal ("Terminal type `%s' is not defined.\n", termtype);
@}
@end smallexample

@noindent
Here we assume the function @code{fatal} prints an error message and exits.

If the environment variable @code{TERMCAP} is defined, its value is used to
override the terminal type data base.  The function @code{tgetent} checks
the value of @code{TERMCAP} automatically.  If the value starts with
@samp{/} then it is taken as a file name to use as the data base file,
instead of @file{/etc/termcap} which is the standard data base.  If the
value does not start with @samp{/} then it is itself used as the terminal
description, provided that the terminal type @var{termtype} is among the
types it claims to apply to.  @xref{Data Base}, for information on the
format of a terminal description.@refill

@node Interrogate, Initialize, Find, Library
@section Interrogating the Terminal Description

Each piece of information recorded in a terminal description is called a
@dfn{capability}.  Each defined terminal capability has a two-letter code
name and a specific meaning.  For example, the number of columns is named
@samp{co}.  @xref{Capabilities}, for definitions of all the standard
capability names.

Once you have found the proper terminal description with @code{tgetent}
(@pxref{Find}), your application program must @dfn{interrogate} it for
various terminal capabilities.  You must specify the two-letter code of
the capability whose value you seek.

Capability values can be numeric, boolean (capability is either present or
absent) or strings.  Any particular capability always has the same value
type; for example, @samp{co} always has a numeric value, while @samp{am}
(automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion
command) always has a string value.  The documentation of each capability
says which type of value it has.@refill

There are three functions to use to get the value of a capability,
depending on the type of value the capability has.  Here are their
declarations in ANSI C:

@findex tgetnum
@findex tgetflag
@findex tgetstr
@example
int tgetnum (char *@var{name});
int tgetflag (char *@var{name});
char *tgetstr (char *@var{name}, char **@var{area});
@end example

@table @code
@item tgetnum
Use @code{tgetnum} to get a capability value that is numeric.  The
argument @var{name} is the two-letter code name of the capability.  If
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.
* Not Enough::  When there is not enough 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, Not Enough,  , 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 Not Enough, Describe Padding, Why Pad, Padding
@subsection When There Is Not Enough Padding

There are several common manifestations of insufficient padding.

@itemize @bullet
@item
Emacs displays @samp{I-search: ^Q-} at the bottom of the screen.

This means that the terminal thought its buffer was getting full of
display commands, so it tried to tell the computer to stop sending
any.

@item
The screen is garbled intermittently, or the details of garbling vary
when you repeat the action.  (A garbled screen could be due to a
command which is simply incorrect, or to user option in the terminal
which doesn't match the assumptions of the terminal description, but
this usually leads to reproducible failure.)

This means that the buffer did get full, and some commands were lost.
Many changeable factors can change which ones are lost.

@item
Screen is garbled at high output speeds but not at low speeds.
Padding problems nearly always go away at low speeds, usually even at
1200 baud.

This means that a high enough speed permits commands to arrive faster
than they can be executed.
@end itemize

Although any obscure command on an obscure terminal might lack padding,
in practice problems arise most often from the clearing commands
@samp{cl} and @samp{cd} (@pxref{Clearing}), the scrolling commands
@samp{sf} and @samp{sr} (@pxref{Scrolling}), and the line insert/delete
commands @samp{al} and @samp{dl} (@pxref{Insdel Line}).

Occasionally the terminal description fails to define @samp{sf} and some
programs will use @samp{do} instead, so you may get a problem with
@samp{do}.  If so, first define @samp{sf} just like @samp{do}, then
add some padding to @samp{sf}.

The best strategy is to add a lot of padding at first, perhaps 200 msec.
This is much more than enough; in fact, it should cause a visible slowdown.
(If you don't see a slowdown, the change has not taken effect;
@pxref{Changing}.)  If this makes the problem go away, you have found the
right place to add padding; now reduce the amount until the problem comes
back, then increase it again.  If the problem remains, either it is in some
other capability or it is not a matter of padding at all.