termcap.texinfo

早期freebsd实现

\input texinfo  @c -*-texinfo-*-
@setfilename ../info/termcap
@settitle The Termcap Library
@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
@titlepage
@sp 6
@center @titlefont{Termcap}
@sp 1
@center The Termcap Library and Data Base
@sp 4
@center First Edition
@sp 1
@center April 1988
@sp 5
@center Richard M. Stallman
@sp 1
@center Free Software Foundation
@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.
@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.
@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, 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.

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

@example
#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 example

@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