NetBSD/lib/libterm/termcap.3

.\"	$NetBSD: termcap.3,v 1.19 2000/05/20 13:55:10 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"
.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 .
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.  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.  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.  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
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 .