522 lines
13 KiB
Groff
522 lines
13 KiB
Groff
.\" $NetBSD: termcap.3,v 1.20 2000/05/28 09:58:15 blymn Exp $
|
|
.\"
|
|
.\" Copyright (c) 1980, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)termcap.3 8.2 (Berkeley) 12/11/93
|
|
.\"
|
|
.Dd September 30, 1999
|
|
.Dt TERMCAP 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tgetent ,
|
|
.Nm tgetnum ,
|
|
.Nm tgetflag ,
|
|
.Nm tgetstr ,
|
|
.Nm tgoto ,
|
|
.Nm tputs
|
|
.Nd terminal independent operation routines
|
|
.Sh LIBRARY
|
|
.Lb libtermcap
|
|
.Sh SYNOPSIS
|
|
.Fd #include <termcap.h>
|
|
.Vt char PC;
|
|
.Vt char *BC;
|
|
.Vt char *UP;
|
|
.Vt short ospeed;
|
|
.Vt struct tinfo *info;
|
|
.Ft int
|
|
.Fn tgetent "char *bp" "char *name"
|
|
.Ft int
|
|
.Fn tgetnum "char *id"
|
|
.Ft int
|
|
.Fn tgetflag "char *id"
|
|
.Ft char *
|
|
.Fn tgetstr "char *id" "char **area"
|
|
.Ft char *
|
|
.Fn tgoto "char *cm" "int destcol" "int destline"
|
|
.Ft void
|
|
.Fn tputs "char *cp" "int affcnt" "int (*outc)(int)"
|
|
.Ft int
|
|
.Fn t_getent "struct tinfo **info" "char *name"
|
|
.Ft int
|
|
.Fn t_getnum "struct tinfo *info" "char *id"
|
|
.Ft int
|
|
.Fn t_getflag "struct tinfo *info" "char *id"
|
|
.Ft char *
|
|
.Fn t_getstr "struct tinfo *info" "char *id" "char **area" "size_t *limit"
|
|
.Ft char *
|
|
.Fn t_agetstr "struct tinfo *info" "char *id" "char **buffer" "char **area"
|
|
.Ft int
|
|
.Fn t_getterm "struct tinfo *info" "char **area" "size_t *limit"
|
|
.Ft int
|
|
.Fn t_goto "struct tinfo *info" "char *id" "int destcol" "int destline" "char *buffer" "size_t limit"
|
|
.Ft int
|
|
.Fn t_puts "struct tinfo *info" "char *cp" "int affcnt" "void (*outc)(char, void *)" "void *args"
|
|
.Ft void
|
|
.Fn t_freent "char *info"
|
|
.Ft int
|
|
.Fn t_setinfo "struct tinfo **info" "const char *entry"
|
|
.Sh DESCRIPTION
|
|
These functions extract and use capabilities from a terminal capability data
|
|
base, usually
|
|
.Pa /usr/share/misc/termcap ,
|
|
the format of which is described in
|
|
.Xr termcap 5 .
|
|
These are low level routines;
|
|
see
|
|
.Xr curses 3
|
|
for a higher level package.
|
|
.Pp
|
|
The
|
|
.Fn tgetent
|
|
function
|
|
extracts the entry for terminal
|
|
.Fa name
|
|
into the buffer at
|
|
.Fa bp .
|
|
The
|
|
.Fa bp
|
|
argument
|
|
should be a character buffer of size
|
|
1024 and must be retained through all subsequent calls to
|
|
.Fn tgetnum ,
|
|
.Fn tgetflag ,
|
|
and
|
|
.Fn tgetstr .
|
|
The
|
|
.Fn tgetent
|
|
function
|
|
returns \-1 if none of the
|
|
.Nm termcap
|
|
data base files could be opened,
|
|
0 if the terminal name given does not have an entry,
|
|
and 1 if all goes well.
|
|
It will look in the environment for a
|
|
.Ev TERMCAP
|
|
variable.
|
|
If found, and the value does not begin with a slash, the value does
|
|
not contain the ZZ capability (see
|
|
.Em NOTES
|
|
for a description of this capability),
|
|
and the terminal type
|
|
.Fa name
|
|
is the same as the environment string
|
|
.Ev TERM ,
|
|
the
|
|
.Ev TERMCAP
|
|
string is used instead of reading a
|
|
.Nm termcap
|
|
file. If the value does contain the ZZ capability then the
|
|
.Ev TERM
|
|
environment string is used to read
|
|
.Nm termcap ,
|
|
if the read fails for any reason the value of
|
|
.Ev TERMCAP
|
|
will be used despite it containing ZZ.
|
|
If
|
|
.Ev TERMCAP
|
|
does begin with a slash, the string is used as a path name
|
|
of the
|
|
.Nm termcap
|
|
file to search.
|
|
If
|
|
.Ev TERMCAP
|
|
does not begin with a slash and
|
|
.Fa name
|
|
is different from
|
|
.Ev TERM ,
|
|
.Fn tgetent
|
|
searches the files
|
|
.Pa $HOME/.termcap
|
|
and
|
|
.Pa /usr/share/misc/termcap ,
|
|
in that order, unless the environment variable
|
|
.Ev TERMPATH
|
|
exists,
|
|
in which case it specifies a list of file pathnames
|
|
(separated by spaces or colons) to be searched instead.
|
|
Whenever multiple files are searched and a
|
|
.Sy tc
|
|
field occurs in the requested entry, the entry it names must be found
|
|
in the same file or one of the succeeding files.
|
|
This can speed up entry into programs that call
|
|
.Fn tgetent ,
|
|
as well as help debug new terminal descriptions
|
|
or make one for your terminal if you can't write the file
|
|
.Pa /usr/share/misc/termcap .
|
|
.Pp
|
|
The
|
|
.Fn tgetnum
|
|
function
|
|
gets the numeric value of capability
|
|
.Fa id ,
|
|
returning \-1 if it is not given for the terminal.
|
|
The
|
|
.Fn tgetflag
|
|
function
|
|
returns 1 if the specified capability is present in
|
|
the terminal's entry, 0 if it is not.
|
|
The
|
|
.Fn tgetstr
|
|
function
|
|
returns the string value of the capability
|
|
.Fa id ,
|
|
places it in the buffer at
|
|
.Fa area ,
|
|
and advances the
|
|
.Fa area
|
|
pointer.
|
|
It decodes the abbreviations for this field described in
|
|
.Xr termcap 5 ,
|
|
except for cursor addressing and padding information.
|
|
The
|
|
.Fn tgetstr
|
|
function
|
|
returns
|
|
.Dv NULL
|
|
if the capability was not found.
|
|
.Pp
|
|
The
|
|
.Fn tgoto
|
|
function
|
|
returns a cursor addressing string decoded from
|
|
.Fa cm
|
|
to go to column
|
|
.Fa destcol
|
|
in line
|
|
.Fa destline .
|
|
It uses the external variables
|
|
.Va UP
|
|
(from the
|
|
.Sy up
|
|
capability)
|
|
and
|
|
.Va BC
|
|
(if
|
|
.Sy bc
|
|
is given rather than
|
|
.Sy bs )
|
|
if necessary to avoid placing
|
|
.Sy \en ,
|
|
.Sy ^D
|
|
or
|
|
.Sy ^@
|
|
in
|
|
the returned string.
|
|
(Programs which call
|
|
.Fn tgoto
|
|
should be sure to turn off the
|
|
.Dv XTABS
|
|
bit(s),
|
|
since
|
|
.Fn tgoto
|
|
may now output a tab.
|
|
Note that programs using termcap should in general turn off
|
|
.Dv XTABS
|
|
anyway since some terminals use control-I for other functions,
|
|
such as nondestructive space.)
|
|
If a
|
|
.Sy %
|
|
sequence is given which is not understood, then
|
|
.Fn tgoto
|
|
returns
|
|
.Pq Dv OOPS .
|
|
.Pp
|
|
The
|
|
.Fn tputs
|
|
function
|
|
decodes the leading padding information of the string
|
|
.Fa cp ;
|
|
.Fa affcnt
|
|
gives the number of lines affected by the operation, or 1 if this is
|
|
not applicable,
|
|
.Fa outc
|
|
is a routine which is called with each character in turn.
|
|
The external variable
|
|
.Va ospeed
|
|
should contain the output speed of the terminal as encoded by
|
|
.Xr stty 3 .
|
|
The external variable
|
|
.Va PC
|
|
should contain a pad character to be used (from the
|
|
.Sy pc
|
|
capability)
|
|
if a null
|
|
.Pq Sy ^@
|
|
is inappropriate.
|
|
.Pp
|
|
The
|
|
.Fn t_getent
|
|
function operates in a similar manner to the
|
|
.Fn tgetent
|
|
function excepting that the
|
|
.Fa info
|
|
argument is a pointer to a pointer of the opaque type
|
|
.Va tinfo .
|
|
If the call to
|
|
.Fn t_getent
|
|
succeeds then the argument
|
|
.Fa info
|
|
will be updated with the address of an object that contains the termcap
|
|
entry. This pointer can then be passed to calls of
|
|
.Fn t_getnum ,
|
|
.Fn t_getflag
|
|
and
|
|
.Fn t_getstr .
|
|
When the information pointed to by
|
|
.Fa info
|
|
is no longer required any storage associated with the object can be
|
|
released by calling
|
|
.Fn t_freent .
|
|
.Pp
|
|
The functions
|
|
.Fn t_getnum
|
|
and
|
|
.Fn t_getflag
|
|
operate in the same manner as
|
|
.Fn tgetnum
|
|
and
|
|
.Fn tgetflag
|
|
with the exception that the pointer to the termcap object is passed along
|
|
with the id of the capability required.
|
|
.Pp
|
|
The function
|
|
.Fn t_getstr
|
|
performs the same function as
|
|
.Fn tgetstr
|
|
but has a
|
|
.Fa limit
|
|
parameter that gives the number of characters that can be inserted in to
|
|
the array pointed to by
|
|
.Fa area .
|
|
The
|
|
.Fa limit
|
|
argument is updated by the
|
|
.Fn t_getstr
|
|
call to give the number of characters that remain available in
|
|
.Fa area .
|
|
If the t_getstr call fails then
|
|
.Sy NULL
|
|
will be returned and errno set to indicate the failure, ENOENT indicates
|
|
there was no termcap entry for the given
|
|
.Fa id ,
|
|
E2BIG indicates the retrieved entry would have overflowed
|
|
.Fa area .
|
|
If t_getstr is called with
|
|
.Fa area
|
|
being NULL then the size required to hold the capability string will be
|
|
returned in
|
|
.Fa limit
|
|
so the caller can allocate enough storage to hold the capability.
|
|
.Pp
|
|
The function
|
|
.Fn t_agetstr
|
|
performs the same function as
|
|
.Fn t_getstr
|
|
except sufficient memory is first allocated to hold the desired string
|
|
argument before adding it to the buffer. To initialise the buffer for
|
|
.Fn t_agetstr
|
|
the first call must be done with the contents of
|
|
.Fa buffer
|
|
set to NULL. Subsequent calls to
|
|
.Fn t_agetstr
|
|
can pass
|
|
.Fa buffer
|
|
and
|
|
.Fa area
|
|
in unmodified and the requested string argument will be appended to
|
|
the buffer after sufficient memory has been allocated. Modifying either
|
|
.Fa buffer
|
|
or
|
|
.Fa area
|
|
between calls to
|
|
.Fn t_agetstr
|
|
will certainly lead to the function misbehaving. When the storage
|
|
allocated by
|
|
.Fn t_agetstr
|
|
is no longer required it can be freed by passing the pointer contained
|
|
in
|
|
.Fa buffer
|
|
to
|
|
.Fn free .
|
|
If an error occurs within
|
|
.Fn t_agetstr
|
|
a NULL will be returned and
|
|
.Fa buffer
|
|
and
|
|
.Fa area
|
|
will remain unmodified.
|
|
.Em NOTE
|
|
.Fn t_agetstr
|
|
uses
|
|
.Fn realloc
|
|
to reallocate the buffer memory so saving a copy of either
|
|
.Fa buffer
|
|
or
|
|
.Fa area
|
|
for use after subsequent calls to
|
|
.Fn t_agetstr
|
|
is likely to fail. It is best to keep offsets from
|
|
.Fa buffer
|
|
to the desired string and calculate pointer addresses only after all
|
|
the calls to
|
|
.Fn t_agetstr
|
|
have been done.
|
|
.Pp
|
|
The function
|
|
.Fn t_getterm
|
|
returns a copy of the termcap name string of the termcap entry
|
|
associated with
|
|
.Fa info
|
|
in the buffer pointed to by
|
|
.Fa area .
|
|
.Fn t_getterm
|
|
returns 0 on success and -1 on error. On error errno will be set to
|
|
EINVAL if the termcap entry in
|
|
.Fa info
|
|
is malformed or E2BIG if the size of the name exceeds the size
|
|
specified by
|
|
.Fa limit .
|
|
If
|
|
.Fa area
|
|
is NULL then the size required to hold the terminal name will be
|
|
returned in
|
|
.Fa limit
|
|
allowing sufficient storage to be allocated. If
|
|
.Fa limit
|
|
is NULL then no bounds checking will be performed.
|
|
.Pp
|
|
The
|
|
.Fn t_goto
|
|
function is the same as the
|
|
.Fn tgoto
|
|
function excepting that the capabilities for
|
|
.Sy up
|
|
and
|
|
.Sy bc
|
|
are extracted from the
|
|
.Fa info
|
|
object and that the string formed by
|
|
.Fn t_goto
|
|
is placed in the
|
|
.Fa buffer
|
|
argument, the number of characters allowed to be placed in
|
|
.Fa buffer
|
|
is controlled by
|
|
.Fa limit .
|
|
If the expansion performed by
|
|
.Fn t_goto
|
|
would exceed the space in
|
|
.Fa buffer
|
|
then
|
|
.Fn t_goto
|
|
will return -1 and set errno to
|
|
.Sy E2BIG .
|
|
The function
|
|
.Fn t_puts
|
|
is similar to the
|
|
.Fn tputs
|
|
function excepting that
|
|
.Fa info
|
|
holds a pointer to the termcap object that was returned by a previous
|
|
.Fn t_getent
|
|
call, this object will be used to retrieve the
|
|
.Sy pc
|
|
attribute for the terminal. The
|
|
.Fa outc
|
|
function is a pointer to a function that will be called by
|
|
.Fn t_puts
|
|
to output each character in the
|
|
.Fa cp
|
|
string. The
|
|
.Fa outc
|
|
function will be called with two parameters. The first is the character
|
|
to be printed and the second is an optional argument that was passed to
|
|
.Fn t_puts
|
|
in the
|
|
.Fa args
|
|
argument. The interpretation of the contents of
|
|
.Fa args
|
|
is dependent soley on the implementation of
|
|
.Fa outc.
|
|
.Pp
|
|
The
|
|
.Fn t_setinfo
|
|
function allows the termcap entry contained in the
|
|
.Fa entry
|
|
string to be inserted into the the
|
|
.Fa info
|
|
structure. Memory sufficient to hold the contents of
|
|
.Fa entry
|
|
is automatically allocated. This allows the programmer to provide a
|
|
fail over terminal capability string if fetching the termcap entry
|
|
from the termcap database fails. The format of the string
|
|
.Fa entry
|
|
is assumed to be a valid termcap entry.
|
|
.Pp
|
|
NOTE: A special capability of
|
|
.Fa ZZ
|
|
is added to the end of the termcap entry retrieved. The number that follows
|
|
this entry is the address of the buffer allocated to hold the full termcap
|
|
entry. The caller may retrieve the pointer to the extended buffer by
|
|
performing a
|
|
.Fn tgetstr
|
|
to retrieve the
|
|
.Fa ZZ
|
|
capability, the string is the output of a
|
|
.Fn printf
|
|
%p and may be converted back to a pointer using
|
|
.Fn sscanf
|
|
or similar. The ZZ capability is only necessary if the caller wishes to
|
|
directly manipulate the termcap entry, all the termcap function calls
|
|
automatically use the extended buffer to retrieve terminal capabilities.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/misc/termcap -compact
|
|
.It Pa /usr/lib/libtermcap.a
|
|
.Fl l Ar termcap
|
|
library (also known as
|
|
.Fl l Ar termlib )
|
|
.It Pa /usr/share/misc/termcap
|
|
standard terminal capability data base
|
|
.It Pa $HOME/.termcap
|
|
user's terminal capability data base
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ex 1 ,
|
|
.Xr curses 3 ,
|
|
.Xr termcap 5
|
|
.Sh HISTORY
|
|
The
|
|
.Nm termcap
|
|
functions appeared in
|
|
.Bx 4.0 .
|