termcap.texi

linux下bash的源码

\input texinfo  @c -*-texinfo-*-
@setfilename termcap
@settitle The Termcap Library
@smallbook

@ifinfo
This file documents the termcap library of the GNU system.

Copyright (C) 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@setchapternewpage odd

@c @shorttitlepage The Termcap Manual

@titlepage
@ignore
@sp 6
@center @titlefont{Termcap}
@sp 1
@center The Termcap Library and Data Base
@sp 4
@center Second Edition
@sp 1
@center December 1992
@sp 5
@center Richard M. Stallman
@sp 1
@center Free Software Foundation
@end ignore

@c Real title page
@title The Termcap Manual
@subtitle The Termcap Library and Data Base
@subtitle Second Edition
@subtitle December 1992
@author Richard M. Stallman
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988 Free Software Foundation, Inc.

Published by the Free Software Foundation
(675 Mass Ave, Cambridge MA 02139).
Printed copies are available for $10 each.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@sp 2
Cover art by Etienne Suvasa.
@end titlepage
@page

@synindex vr fn

@node Top, Introduction, (dir), (dir)

@menu
* Introduction::  What is termcap?  Why this manual?
* Library::     The termcap library functions.
* Data Base::   What terminal descriptions in @file{/etc/termcap} look like.
* Capabilities::  Definitions of the individual terminal capabilities:
                 how to write them in descriptions, and how to use
                 their values to do display updating.
* Summary::     Brief table of capability names and their meanings.
* Var Index::   Index of C functions and variables.
* Cap Index::   Index of termcap capabilities.
* Index::       Concept index.

 --- The Detailed Node Listing ---

The Termcap Library

* Preparation::  Preparing to use the termcap library.
* Find::        Finding the description of the terminal being used.
* Interrogate::  Interrogating the description for particular capabilities.
* Initialize::  Initialization for output using termcap.
* Padding::     Outputting padding.
* Parameters::  Encoding parameters such as cursor positions.

Padding

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

Filling In Parameters

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

Sending Display Commands with Parameters

* tparam::      The general case, for GNU termcap only.
* tgoto::       The special case of cursor motion.

The Format of the Data Base

* Format::      Overall format of a terminal description.
* Capability Format::  Format of capabilities within a description.
* Naming::      Naming conventions for terminal types.
* Inheriting::  Inheriting part of a description from
a related terminal type.
* Changing::    When changes in the data base take effect.

Definitions of the Terminal Capabilities

* Basic::       Basic characteristics.
* Screen Size::  Screen size, and what happens when it changes.
* Cursor Motion::  Various ways to move the cursor.
* Wrapping::    What happens if you write a character in the last column.
* Scrolling::   Pushing text up and down on the screen.
* 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 Introduction, Library, Top, Top
@unnumbered Introduction

@cindex termcap
@dfn{Termcap} is a library and data base that enables programs to use
display terminals in a terminal-independent manner.  It originated in
Berkeley Unix.

The termcap data base describes the capabilities of hundreds of different
display terminals in great detail.  Some examples of the information
recorded for a terminal could include how many columns wide it is, what
string to send to move the cursor to an arbitrary position (including how
to encode the row and column numbers), how to scroll the screen up one or
several lines, and how much padding is needed for such a scrolling
operation.

The termcap library is provided for easy access this data base in programs
that want to do terminal-independent character-based display output.

This manual describes the GNU version of the termcap library, which has
some extensions over the Unix version.  All the extensions are identified
as such, so this manual also tells you how to use the Unix termcap.

The GNU version of the termcap library is available free as source code,
for use in free programs, and runs on Unix and VMS systems (at least).  You
can find it in the GNU Emacs distribution in the files @file{termcap.c} and
@file{tparam.c}.

This manual was written for the GNU project, whose goal is to develop a
complete free operating system upward-compatible with Unix for user
programs.  The project is approximately two thirds complete.  For more
information on the GNU project, including the GNU Emacs editor and the
mostly-portable optimizing C compiler, send one dollar to

@display
Free Software Foundation
675 Mass Ave
Cambridge, MA 02139
@end display

@node Library, Data Base, Introduction, Top
@chapter The Termcap Library

The termcap library is the application programmer's interface to the
termcap data base.  It contains functions for the following purposes:

@itemize @bullet
@item
Finding the description of the user's terminal type (@code{tgetent}).

@item
Interrogating the description for information on various topics
(@code{tgetnum}, @code{tgetflag}, @code{tgetstr}).

@item
Computing and performing padding (@code{tputs}).

@item
Encoding numeric parameters such as cursor positions into the
terminal-specific form required for display commands (@code{tparam},
@code{tgoto}).
@end itemize

@menu
* Preparation::  Preparing to use the termcap library.
* Find::        Finding the description of the terminal being used.
* Interrogate::  Interrogating the description for particular capabilities.
* Initialize::  Initialization for output using termcap.
* Padding::     Outputting padding.
* Parameters::  Encoding parameters such as cursor positions.
@end menu

@node Preparation, Find,  , Library
@section Preparing to Use the Termcap Library

To use the termcap library in a program, you need two kinds of preparation:

@itemize @bullet
@item
The compiler needs declarations of the functions and variables in the
library.

On GNU systems, it suffices to include the header file
@file{termcap.h} in each source file that uses these functions and
variables.@refill

On Unix systems, there is often no such header file.  Then you must
explictly declare the variables as external.  You can do likewise for
the functions, or let them be implicitly declared and cast their
values from type @code{int} to the appropriate type.

We illustrate the declarations of the individual termcap library
functions with ANSI C prototypes because they show how to pass the
arguments.  If you are not using the GNU C compiler, you probably
cannot use function prototypes, so omit the argument types and names
from your declarations.

@item
The linker needs to search the library.  Usually either
@samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will
do this.@refill
@end itemize

@node Find, Interrogate, Preparation, Library
@section Finding a Terminal Description: @code{tgetent}

@findex tgetent
An application program that is going to use termcap must first look up the
description of the terminal type in use.  This is done by calling
@code{tgetent}, whose declaration in ANSI Standard C looks like:

@example
int tgetent (char *@var{buffer}, char *@var{termtype});
@end example

@noindent
This function finds the description and remembers it internally so that
you can interrogate it about specific terminal capabilities
(@pxref{Interrogate}).

The argument @var{termtype} is a string which is the name for the type of
terminal to look up.  Usually you would obtain this from the environment
variable @code{TERM} using @code{getenv ("TERM")}.

If you are using the GNU version of termcap, you can alternatively ask
@code{tgetent} to allocate enough space.  Pass a null pointer for
@var{buffer}, and @code{tgetent} itself allocates the storage using
@code{malloc}.  In this case the returned value on success is the address
of the storage, cast to @code{int}.  But normally there is no need for you
to look at the address.  Do not free the storage yourself.@refill

With the Unix version of termcap, you must allocate space for the
description yourself and pass the address of the space as the argument
@var{buffer}.  There is no way you can tell how much space is needed, so
the convention is to allocate a buffer 2048 characters long and assume that
is enough.  (Formerly the convention was to allocate 1024 characters and
assume that was enough.  But one day, for one kind of terminal, that was
not enough.)

No matter how the space to store the description has been obtained,
termcap records its address internally for use when you later interrogate
the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}.  If
the buffer was allocated by termcap, it will be freed by termcap too if you
call @code{tgetent} again.  If the buffer was provided by you, you must
make sure that its contents remain unchanged for as long as you still plan
to interrogate the description.@refill

The return value of @code{tgetent} is @minus{}1 if there is some difficulty
accessing the data base of terminal types, 0 if the data base is accessible
but the specified type is not defined in it, and some other value
otherwise.