339 lines
13 KiB
Plaintext
339 lines
13 KiB
Plaintext
.\"***************************************************************************
|
|
.\" Copyright 2018-2020,2021 Thomas E. Dickey *
|
|
.\" Copyright 1998-2017,2018 Free Software Foundation, Inc. *
|
|
.\" *
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|
.\" copy of this software and associated documentation files (the *
|
|
.\" "Software"), to deal in the Software without restriction, including *
|
|
.\" without limitation the rights to use, copy, modify, merge, publish, *
|
|
.\" distribute, distribute with modifications, sublicense, and/or sell *
|
|
.\" copies of the Software, and to permit persons to whom the Software is *
|
|
.\" furnished to do so, subject to the following conditions: *
|
|
.\" *
|
|
.\" The above copyright notice and this permission notice shall be included *
|
|
.\" in all copies or substantial portions of the Software. *
|
|
.\" *
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
.\" *
|
|
.\" Except as contained in this notice, the name(s) of the above copyright *
|
|
.\" holders shall not be used in advertising or otherwise to promote the *
|
|
.\" sale, use or other dealings in this Software without prior written *
|
|
.\" authorization. *
|
|
.\"***************************************************************************
|
|
.\"
|
|
.\" $Id: curs_termcap.3x,v 1.48 2021/01/09 11:07:15 tom Exp $
|
|
.TH curs_termcap 3X ""
|
|
.ie \n(.g .ds `` \(lq
|
|
.el .ds `` ``
|
|
.ie \n(.g .ds '' \(rq
|
|
.el .ds '' ''
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.na
|
|
.hy 0
|
|
.ds n 5
|
|
.SH NAME
|
|
\fBPC\fR,
|
|
\fBUP\fR,
|
|
\fBBC\fR,
|
|
\fBospeed\fR,
|
|
\fBtgetent\fR,
|
|
\fBtgetflag\fR,
|
|
\fBtgetnum\fR,
|
|
\fBtgetstr\fR,
|
|
\fBtgoto\fR,
|
|
\fBtputs\fR \- \fBcurses\fR emulation of termcap
|
|
.ad
|
|
.hy
|
|
.SH SYNOPSIS
|
|
\fB#include <curses.h>\fR
|
|
.br
|
|
\fB#include <term.h>\fR
|
|
.sp
|
|
\fBextern char PC;\fR
|
|
.br
|
|
\fBextern char * UP;\fR
|
|
.br
|
|
\fBextern char * BC;\fR
|
|
.br
|
|
\fBextern @NCURSES_OSPEED@ ospeed;\fR
|
|
.sp
|
|
\fBint tgetent(char *\fP\fIbp\fP\fB, const char *\fP\fIname\fP\fB);\fR
|
|
.br
|
|
\fBint tgetflag(const char *\fP\fIid\fP\fB);\fR
|
|
.br
|
|
\fBint tgetnum(const char *\fP\fIid\fP\fB);\fR
|
|
.br
|
|
\fBchar *tgetstr(const char *\fP\fIid\fP\fB, char **\fP\fIarea\fP\fB);\fR
|
|
.br
|
|
\fBchar *tgoto(const char *\fP\fIcap\fP\fB, int \fP\fIcol\fP\fB, int \fP\fIrow\fP\fB);\fR
|
|
.br
|
|
\fBint tputs(const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fR
|
|
.br
|
|
.SH DESCRIPTION
|
|
These routines are included as a conversion aid for programs that use
|
|
the \fItermcap\fR library.
|
|
Their parameters are the same, but the
|
|
routines are emulated using the \fIterminfo\fR database.
|
|
Thus, they
|
|
can only be used to query the capabilities of entries for which a
|
|
terminfo entry has been compiled.
|
|
.SS INITIALIZATION
|
|
.PP
|
|
The \fBtgetent\fR routine loads the entry for \fIname\fR.
|
|
It returns:
|
|
.RS 3
|
|
.TP 3
|
|
1
|
|
on success,
|
|
.TP 3
|
|
0
|
|
if there is no such entry
|
|
(or that it is a generic type, having too little information for curses
|
|
applications to run), and
|
|
.TP 3
|
|
\-1
|
|
if the terminfo database could not be found.
|
|
.RE
|
|
.PP
|
|
This differs from the \fItermcap\fP library in two ways:
|
|
.RS 3
|
|
.bP
|
|
The emulation ignores the buffer pointer \fIbp\fR.
|
|
The \fItermcap\fP library would store a copy of the terminal
|
|
description in the area referenced by this pointer.
|
|
However, ncurses stores its terminal descriptions in compiled
|
|
binary form, which is not the same thing.
|
|
.bP
|
|
There is a difference in return codes.
|
|
The \fItermcap\fP library does not check if the terminal
|
|
description is marked with the \fIgeneric\fP capability,
|
|
or if the terminal description has cursor-addressing.
|
|
.RE
|
|
.SS CAPABILITY VALUES
|
|
.PP
|
|
The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR,
|
|
or zero if it is not available.
|
|
.PP
|
|
The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR,
|
|
or \-1 if it is not available.
|
|
.PP
|
|
The \fBtgetstr\fR routine returns the string entry for \fIid\fR,
|
|
or zero if it is not available.
|
|
Use \fBtputs\fR to output the returned string.
|
|
The \fIarea\fP parameter is used as follows:
|
|
.RS 3
|
|
.bP
|
|
It is assumed to be the address of a pointer to a buffer managed by the
|
|
calling application.
|
|
.bP
|
|
However, ncurses checks to ensure that \fBarea\fP is not NULL,
|
|
and also that the resulting buffer pointer is not NULL.
|
|
If either check fails, the \fIarea\fP parameter is ignored.
|
|
.bP
|
|
If the checks succeed, ncurses also copies the return value to
|
|
the buffer pointed to by \fIarea\fR,
|
|
and the \fIarea\fR value will be updated to point past the null ending
|
|
this value.
|
|
.bP
|
|
The return value itself is an address in the terminal description which
|
|
is loaded into memory.
|
|
.RE
|
|
.PP
|
|
Only the first two characters of the \fBid\fR parameter of
|
|
\fBtgetflag\fR,
|
|
\fBtgetnum\fR and
|
|
\fBtgetstr\fR are compared in lookups.
|
|
.SS FORMATTING CAPABILITIES
|
|
.PP
|
|
The \fBtgoto\fR routine expands the given capability using the parameters.
|
|
.bP
|
|
Because the capability may have padding characters,
|
|
the output of \fBtgoto\fP should be passed to \fBtputs\fR
|
|
rather than some other output function such as \fBprintf\fP.
|
|
.bP
|
|
While \fBtgoto\fP is assumed to be used for the two-parameter
|
|
cursor positioning capability,
|
|
termcap applications also use it for single-parameter capabilities.
|
|
.IP
|
|
Doing this shows a quirk in \fBtgoto\fP: most hardware
|
|
terminals use cursor addressing with \fIrow\fP first,
|
|
but the original developers of the termcap interface chose to
|
|
put the \fIcolumn\fP parameter first.
|
|
The \fBtgoto\fP function swaps the order of parameters.
|
|
It does this also for calls requiring only a single parameter.
|
|
In that case, the first parameter is merely a placeholder.
|
|
.bP
|
|
Normally the ncurses library is compiled with terminfo support.
|
|
In that case, \fBtgoto\fP uses \fBtparm\fP(3X) (a more capable formatter).
|
|
.IP
|
|
However, \fBtparm\fP is not a \fItermcap\fP feature,
|
|
and portable \fItermcap\fP applications should not rely upon its availability.
|
|
.PP
|
|
The \fBtputs\fR routine is described on the \fBcurs_terminfo\fR(3X) manual
|
|
page.
|
|
It can retrieve capabilities by either termcap or terminfo name.
|
|
.SS GLOBAL VARIABLES
|
|
.PP
|
|
The variables
|
|
\fBPC\fR,
|
|
\fBUP\fR and
|
|
\fBBC\fR
|
|
are set by \fBtgetent\fR to the terminfo entry's data for
|
|
\fBpad_char\fR,
|
|
\fBcursor_up\fR and
|
|
\fBbackspace_if_not_bs\fR,
|
|
respectively.
|
|
\fBUP\fR is not used by ncurses.
|
|
\fBPC\fR is used in the \fBtdelay_output\fR function.
|
|
\fBBC\fR is used in the \fBtgoto\fR emulation.
|
|
The variable \fBospeed\fR is set by ncurses in a system-specific coding
|
|
to reflect the terminal speed.
|
|
.
|
|
.SH RETURN VALUE
|
|
Except where explicitly noted,
|
|
routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
|
|
(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
|
|
completion.
|
|
.PP
|
|
Routines that return pointers return \fBNULL\fR on error.
|
|
.SH BUGS
|
|
If you call \fBtgetstr\fR to fetch \fBca\fR or any other parameterized string,
|
|
be aware that it will be returned in terminfo notation, not the older and
|
|
not-quite-compatible termcap notation.
|
|
This will not cause problems if all
|
|
you do with it is call \fBtgoto\fR or \fBtparm\fR, which both expand
|
|
terminfo-style strings as terminfo.
|
|
(The \fBtgoto\fR function, if configured to support termcap, will check
|
|
if the string is indeed terminfo-style by looking for "%p" parameters or
|
|
"$<..>" delays, and invoke a termcap-style parser if the string does not
|
|
appear to be terminfo).
|
|
.PP
|
|
Because terminfo conventions for representing padding in string capabilities
|
|
differ from termcap's, \fBtputs("50");\fR will put out a literal \*(``50\*('' rather
|
|
than busy-waiting for 50 milliseconds.
|
|
Cope with it.
|
|
.PP
|
|
Note that termcap has nothing analogous to terminfo's \fBsgr\fR string.
|
|
One consequence of this is that termcap applications assume \fRme\fR
|
|
(terminfo \fBsgr0\fR) does not reset the alternate character set.
|
|
This implementation checks for, and modifies the data shown to the
|
|
termcap interface to accommodate termcap's limitation in this respect.
|
|
.SH PORTABILITY
|
|
.SS Standards
|
|
These functions are provided for supporting legacy applications,
|
|
and should not be used in new programs:
|
|
.bP
|
|
The XSI Curses standard, Issue 4 describes these functions.
|
|
However, they
|
|
are marked TO BE WITHDRAWN and may be removed in future versions.
|
|
.bP
|
|
X/Open Curses, Issue 5 (December 2007) marked the termcap interface
|
|
(along with \fBvwprintw\fP and \fBvwscanw\fP) as withdrawn.
|
|
.PP
|
|
Neither the XSI Curses standard nor the SVr4 man pages documented the return
|
|
values of \fBtgetent\fR correctly, though all three were in fact returned ever
|
|
since SVr1.
|
|
In particular, an omission in the XSI Curses documentation has been
|
|
misinterpreted to mean that \fBtgetent\fR returns \fBOK\fR or \fBERR\fR.
|
|
Because the purpose of these functions is to provide compatibility with
|
|
the \fItermcap\fR library, that is a defect in XCurses, Issue 4, Version 2
|
|
rather than in ncurses.
|
|
.SS Compatibility with BSD Termcap
|
|
.PP
|
|
External variables are provided for support of certain termcap applications.
|
|
However, termcap applications' use of those variables is poorly documented,
|
|
e.g., not distinguishing between input and output.
|
|
In particular, some applications are reported to declare and/or
|
|
modify \fBospeed\fR.
|
|
.PP
|
|
The comment that only the first two characters of the \fBid\fR parameter
|
|
are used escapes many application developers.
|
|
The original BSD 4.2 termcap library (and historical relics thereof)
|
|
did not require a trailing null NUL on the parameter name passed
|
|
to \fBtgetstr\fP, \fBtgetnum\fP and \fBtgetflag\fP.
|
|
Some applications assume that the termcap interface does not require
|
|
the trailing NUL for the parameter name.
|
|
Taking into account these issues:
|
|
.bP
|
|
As a special case,
|
|
\fBtgetflag\fP matched against a single-character identifier
|
|
provided that was at the end of the terminal description.
|
|
You should not rely upon this behavior in portable programs.
|
|
This implementation disallows matches against single-character capability names.
|
|
.bP
|
|
This implementation disallows matches by the termcap interface against
|
|
extended capability names which are longer than two characters.
|
|
.PP
|
|
The BSD termcap function \fBtgetent\fP returns the text of a termcap
|
|
entry in the buffer passed as an argument.
|
|
This library (like other terminfo implementations) does not store
|
|
terminal descriptions as text.
|
|
It sets the buffer contents to a null-terminated string.
|
|
.SS Other Compatibility
|
|
This library includes a termcap.h header,
|
|
for compatibility with other implementations.
|
|
But the header is rarely used because the other implementations
|
|
are not strictly compatible.
|
|
.PP
|
|
The original BSD termcap (through 4.3BSD) had no header file which
|
|
gave function prototypes, because that was a feature of ANSI C.
|
|
BSD termcap was written several years before C was standardized.
|
|
However, there were two different termcap.h header files in the BSD
|
|
sources:
|
|
.bP
|
|
One was used internally by the \fIjove\fP editor in 2BSD through 4.4BSD.
|
|
It defined global symbols for the termcap variables which it used.
|
|
.bP
|
|
The other appeared in 4.4BSD Lite Release 2 (mid-1993)
|
|
as part of \fIlibedit\fP (also known as the \fIeditline\fP library).
|
|
The CSRG source history shows that this was added in mid-1992.
|
|
The \fIlibedit\fP header file was used internally,
|
|
as a convenience for compiling the \fIeditline\fP library.
|
|
It declared function prototypes, but no global variables.
|
|
.PP
|
|
The header file from \fIlibedit\fP was added to NetBSD's termcap
|
|
library in mid-1994.
|
|
.PP
|
|
Meanwhile, GNU termcap was under development, starting in 1990.
|
|
The first release (termcap 1.0) in 1991 included a termcap.h header.
|
|
The second release (termcap 1.1) in September 1992 modified the
|
|
header to use \fBconst\fP for the function prototypes in the header
|
|
where one would expect the parameters to be read-only.
|
|
This was a difference versus the original BSD termcap.
|
|
The prototype for \fBtputs\fP also differed,
|
|
but in that instance, it was \fIlibedit\fP which differed from BSD termcap.
|
|
.PP
|
|
A copy of GNU termcap 1.3 was bundled with \fIbash\fP in mid-1993,
|
|
to support the \fIreadline\fP library.
|
|
.PP
|
|
A termcap.h file was provided in ncurses 1.8.1 (November 1993).
|
|
That reflected influence by \fIemacs\fP (rather than \fIjove\fP)
|
|
and GNU termcap:
|
|
.bP
|
|
it provided declarations for a few global symbols used by \fIemacs\fP
|
|
.bP
|
|
it provided function prototypes (using \fBconst\fP).
|
|
.bP
|
|
a prototype for \fBtparam\fP (a GNU termcap feature) was provided.
|
|
.PP
|
|
Later (in mid-1996) the \fBtparam\fP function was removed from ncurses.
|
|
As a result, there are differences between any of the four implementations,
|
|
which must be taken into account by programs which can work with all
|
|
termcap library interfaces.
|
|
.SH SEE ALSO
|
|
\fBcurses\fR(3X),
|
|
\fBputc\fR(3),
|
|
\fBterm_variables\fR(3X),
|
|
\fBterminfo\fR(\*n).
|
|
.sp
|
|
https://invisible-island.net/ncurses/tctest.html
|