termcap.texinfo

早期freebsd实现

explicitly.

When a capability is described as obsolete, this means that programs should
not be written to look for it, but terminal descriptions should still be
written to provide it.

When a capability is described as very obsolete, this means that it should
be omitted from terminal descriptions as well.

@menu
* Basic::             Basic characteristics.
* Screen Size::       Screen size, and what happens when it changes.
* Cursor Motion::     Various ways to move the cursor.
* Scrolling::         Pushing text up and down on the screen.
* Wrapping::          What happens if you write a character in the last column.
* Windows::           Limiting the part of the window that output affects.
* Clearing::          Erasing one or many lines.
* Insdel Line::       Making new blank lines in mid-screen; deleting lines.
* Insdel Char::       Inserting and deleting characters within a line.
* Standout::          Highlighting some of the text.
* Underlining::       Underlining some of the text.
* Cursor Visibility:: Making the cursor more or less easy to spot.
* Bell::              Attracts user's attention; not localized on the screen.
* Keypad::            Recognizing when function keys or arrows are typed.
* Meta Key::          @key{META} acts like an extra shift key.
* Initialization::    Commands used to initialize or reset the terminal.
* Pad Specs::         Info for the kernel on how much padding is needed.
* Status Line::       A status line displays ``background'' information.
* Half-Line::         Moving by half-lines, for superscripts and subscripts.
* Printer::           Controlling auxiliary printers of display terminals.
@end menu

@node Basic, Screen Size, Capabilities, Capabilities
@section Basic Characteristics

This section documents the capabilities that describe the basic and
nature of the terminal, and also those that are relevant to the output
of graphic characters.

@table @samp
@item os
@kindex os
@cindex overstrike
Flag whose presence means that the terminal can overstrike.  This
means that outputting a graphic character does not erase whatever was
present in the same character position before.  The terminals that can
overstrike include printing terminals, storage tubes (all obsolete
nowadays), and many bit-map displays.

@item eo
@kindex eo
Flag whose presence means that outputting a space can erase an
overstrike.  If this is not present and overstriking is supported,
output of a space has no effect except to move the cursor.

@item gn
@kindex gn
@cindex generic terminal type
Flag whose presence means that this terminal type is a generic type
which does not really describe any particular terminal.  Generic types
are intended for use as the default type assigned when the user
connects to the system, with the intention that the user should
specify what type he really has.  One example of a generic type
is the type @samp{network}.

Since the generic type cannot say how to do anything interesting with
the terminal, termcap-using programs will always find that the
terminal is too weak to be supported if the user has failed to specify
a real terminal type in place of the generic one.  The @samp{gn} flag
directs these programs to use a different error message: ``You have
not specified your real terminal type'', rather than ``Your terminal
is not powerful enough to be used''.

@item hc
@kindex hc
Flag whose presence means this is a hardcopy terminal.

@item rp
@kindex rp
@cindex repeat output
String of commands to output a graphic character @var{c}, repeated @var{n}
times.  The first parameter value is the ASCII code for the desired
character, and the second parameter is the number of times to repeat the
character.  Often this command requires padding proportional to the 
number of times the character is repeated.  This effect can be had by
using parameter arithmetic with @samp{%}-sequences to compute the
amount of padding, then generating the result as a number at the front
of the string so that @code{tputs} will treat it as padding.

@item hz
@kindex hz
Flag whose presence means that the ASCII character @samp{~} cannot be
output on this terminal because it is used for display commands.

Programs handle this flag by checking all text to be output and
replacing each @samp{~} with some other character(s).  If this is not
done, the screen will be thoroughly garbled.

The old Hazeltine terminals that required such treatment are probably
very rare today, so you might as well not bother to support this flag.

@item CC
@kindex CC
@cindex command character
String whose presence means the terminal has a settable command
character.  The value of the string is the default command character
(which is usually @key{ESC}).

All the strings of commands in the terminal description should be
written to use the default command character.  If you are writing an
application program that changes the command character, use the
@samp{CC} capability to figure out how to translate all the display
commands to work with the new command character.

Most programs have no reason to look at the @samp{CC} capability.

@item xb
@kindex xb
@cindex Superbee
Flag whose presence identifies Superbee terminals which are unable to
transmit the characters @key{ESC} and @kbd{Control-C}.  Programs which
support this flag are supposed to check the input for the code sequences
sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC}
or @kbd{Control-C} (respectively) had been read.  But this flag is
obsolete, and not worth supporting.
@end table

@node Screen Size, Cursor Motion, Basic, Capabilities
@section Screen Size
@cindex screen size

A terminal description has two capabilities, @samp{co} and @samp{li},
that describe the screen size in columns and lines.  But there is more
to the question of screen size than this.

On some operating systems the ``screen'' is really a window and the
effective width can vary.  On some of these systems, @code{tgetnum}
uses the actual width of the window to decide what value to return for
the @samp{co} capability, overriding what is actually written in the
terminal description.  On other systems, it is up to the application
program to check the actual window width using a system call.  For
example, on BSD 4.3 systems, the system call @code{ioctl} with code
@code{TIOCGWINSZ} will tell you the current screen size.

On all window systems, termcap is powerless to advise the application
program if the user resizes the window.  Application programs must
deal with this possibility in a system-dependent fashion.  On some
systems the C shell handles part of the problem by detecting changes
in window size and setting the @code{TERMCAP} environment variable
appropriately.  This takes care of application programs that are
started subsequently.  It does not help application programs already
running.

On some systems, including BSD 4.3, all programs using a terminal get
a signal named @code{SIGWINCH} whenever the screen size changes.
Programs that use termcap should handle this signal by using
@code{ioctl TIOCGWINSZ} to learn the new screen size.

@table @samp
@item co
@kindex co
@cindex screen size
Numeric value, the width of the screen in character positions.  Even
hardcopy terminals normally have a @samp{co} capability.

@item li
@kindex li
Numeric value, the height of the screen in lines.
@end table

@node Cursor Motion, Wrapping, Screen Size, Capabilities
@section Cursor Motion
@cindex cursor motion

Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen
where a visible mark is displayed, and that most display commands take
effect at the position of the cursor.  It follows that moving the cursor
to a specified location is very important.

There are many terminal capabilities for different cursor motion
operations.  A terminal description should define as many as possible, but
most programs do not need to use most of them.  One capability, @samp{cm},
moves the cursor to an arbitrary place on the screen; this by itself is
sufficient for any application as long as there is no need to support
hardcopy terminals or certain old, weak displays that have only relative
motion commands.  Use of other cursor motion capabilities is an
optimization, enabling the program to output fewer characters in some
common cases.

If you plan to use the relative cursor motion commands in an application
program, you must know what the starting cursor position is.  To do this,
you must keep track of the cursor position and update the records each
time anything is output to the terminal, including graphic characters.
In addition, it is necessary to know whether the terminal wraps after
writing in the rightmost column.  @xref{Wrapping}.

One other motion capability needs special mention: @samp{nw} moves the
cursor to the beginning of the following line, perhaps clearing all the
starting line after the cursor, or perhaps not clearing at all.  This
capability is a least common denominator that is probably supported even by
terminals that cannot do most other things such as @samp{cm} or @samp{do}.
Even hardcopy terminals can support @samp{nw}.

@table @asis
@item @samp{cm}
@kindex cm
String of commands to position the cursor at line @var{l}, column @var{c}.
Both parameters are origin-zero, and are defined relative to the
screen, not relative to display memory.

All display terminals except a few very obsolete ones support @samp{cm},
so it is acceptable for an application program to refuse to operate on
terminals lacking @samp{cm}.

@item @samp{ho}
@kindex ho
@cindex home position
String of commands to move the cursor to the upper left corner of the
screen (this position is called the @dfn{home position}).  In
terminals where the upper left corner of the screen is not the same as
the beginning of display memory, this command must go to the upper
left corner of the screen, not the beginning of display memory.

Every display terminal supports this capability, and many application
programs refuse to operate if the @samp{ho} capability is missing.

@item @samp{ll}
@kindex ll
String of commands to move the cursor to the lower left corner of the
screen.  On some terminals, moving up from home position does this,
but programs should never assume that will work.  Just output the
@samp{ll} string (if it is provided); if moving to home position and
then moving up is the best way to get there, the @samp{ll} command
will do that.

@item @samp{cr}
@kindex cr
String of commands to move the cursor to the beginning of the line it
is on.  If this capability is not specified, many programs assume
they can use the ASCII carriage return character for this.

@item @samp{le}
@kindex le
String of commands to move the cursor left one column.  Unless the
@samp{bw} flag capability is specified, the effect is undefined if the
cursor is at the left margin; do not use this command there.  If
@samp{bw} is present, this command may be used at the left margin, and
it wraps the cursor to the last column of the preceding line.

@item @samp{nd}
@kindex nd
String of commands to move the cursor right one column.  The effect is
undefined if the cursor is at the right margin; do not use this
command there, not even if @samp{am} is present.

@item @samp{up}
@kindex up
String of commands to move the cursor vertically up one line.  The
effect of sending this string when on the top line is undefined;
programs should never use it that way.

@item @samp{do}
@kindex do
String of commands to move the cursor vertically down one line.  The
effect of sending this string when on the bottom line is undefined;
programs should never use it that way.

The original idea was that this string would not contain a newline
character and therefore could be used without disabling the kernel's usual
habit of converting of newline into a carriage-return newline sequence.
But many terminal descriptions do use newline in the @samp{do} string, so
this is not possible; a program which sends the @samp{do} string must
disable output conversion in the kernel (@pxref{Initialize}).

@item @samp{bw}
@kindex bw
Flag whose presence says that @samp{le} may be used in column zero
to move to the last column of the preceding line.  If this flag
is not present, @samp{le} should not be used in column zero.

@item @samp{nw}
@kindex nw
String of commands to move the cursor to start of next line, possibly
clearing rest of line (following the cursor) before moving.

@item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI}
@kindex DO
@kindex LE
@kindex RI
@kindex UP
Strings of commands to move the cursor @var{n} lines down vertically,
up vertically, or @var{n} columns left or right.  Do not attempt to
move past any edge of the screen with these commands; the effect of
trying that is undefined.  Only a few terminal descriptions provide
these commands, and most programs do not use them.

@item @samp{CM}
@kindex CM
String of commands to position the cursor at line @var{l}, column
@var{c}, relative to display memory.  Both parameters are origin-zero.
This capability is present only in terminals where there is a
difference between screen-relative and memory-relative addressing, and
not even in all such terminals.

@item @samp{ch}
@kindex ch
String of commands to position the cursor at column @var{c} in the
same line it is on.  This is a special case of @samp{cm} in which the
vertical position is not changed.  The @samp{ch} capability is
provided only when it is faster to output than @s