.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.59 2023/04/16 18:16:40 tom Exp $
-.TH curs_termcap 3X 2023-04-16 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_termcap.3x,v 1.74 2023/12/02 20:49:04 tom Exp $
+.TH curs_termcap 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.na
-.hy 0
-.ds n 5
+.
.SH NAME
-\fBPC\fP,
-\fBUP\fP,
-\fBBC\fP,
-\fBospeed\fP,
-\fBtgetent\fP,
-\fBtgetflag\fP,
-\fBtgetnum\fP,
-\fBtgetstr\fP,
-\fBtgoto\fP,
-\fBtputs\fP \- \fBcurses\fP emulation of termcap
-.ad
-.hy
+\fB\%PC\fP,
+\fB\%UP\fP,
+\fB\%BC\fP,
+\fB\%ospeed\fP,
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+\fB\%tgetstr\fP,
+\fB\%tgoto\fP,
+\fB\%tputs\fP \-
+\fIcurses\fR emulation of \fItermcap\fR
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.br
-\fB#include <term.h>\fP
-.sp
-\fBextern char PC;\fP
-.br
-\fBextern char * UP;\fP
-.br
-\fBextern char * BC;\fP
-.br
-\fBextern @NCURSES_OSPEED@ ospeed;\fP
-.sp
-\fBint tgetent(char *\fIbp\fB, const char *\fIname\fB);\fR
-.br
-\fBint tgetflag(const char *\fIid\fB);\fR
-.br
-\fBint tgetnum(const char *\fIid\fB);\fR
-.br
-\fBchar *tgetstr(const char *\fIid\fB, char **\fIarea\fB);\fR
-.br
-\fBchar *tgoto(const char *\fIcap\fB, int \fIcol\fB, int \fIrow\fB);\fR
-.br
-\fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR
-.br
+.nf
+\fB#include <curses.h>
+\fB#include <term.h>
+.PP
+\fBextern char PC;
+\fBextern char * UP;
+\fBextern char * BC;
+\fBextern @NCURSES_OSPEED@ ospeed;
+.PP
+\fBint tgetent(char *\fIbp\fP, const char *\fIname\fP);
+\fBint tgetflag(const char *\fIid\fP);
+\fBint tgetnum(const char *\fIid\fP);
+\fBchar *tgetstr(const char *\fIid\fP, char **\fIarea\fP);
+\fBchar *tgoto(const char *\fIcap\fP, int \fIcol\fP, int \fIrow\fP);
+\fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
+.fi
.SH DESCRIPTION
These routines are included as a conversion aid for programs that use
the \fItermcap\fP library.
can only be used to query the capabilities of entries for which a
terminfo entry has been compiled.
.SS Initialization
-.PP
The \fBtgetent\fP routine loads the entry for \fIname\fP.
It returns:
.RS 3
or if the terminal description has cursor-addressing.
.RE
.SS Capability Values
-.PP
The \fBtgetflag\fP routine gets the boolean entry for \fIid\fP,
or zero if it is not available.
.PP
\fBtgetnum\fP and
\fBtgetstr\fP are compared in lookups.
.SS Formatting Capabilities
-.PP
The \fBtgoto\fP routine expands the given capability using the parameters.
.bP
Because the capability may have padding characters,
page.
It can retrieve capabilities by either termcap or terminfo name.
.SS Global Variables
-.PP
The variables
\fBPC\fP,
\fBUP\fP and
and the functions which return capability values such as \fBtgetstr\fP.
One could use
.sp
- \fBdel_curterm(cur_term);\fP
+ \fBdel_curterm(cur_term);\fP
.sp
.PP
to free this memory, but there is an additional complication with ncurses.
It uses a fixed-size \fIpool\fP of storage locations,
-one per setting of the \fBTERM\fP variable when \fBtgetent\fP is called.
+one per setting of the \fITERM\fP variable when \fBtgetent\fP is called.
The \fBscreen\fP(1) program relies upon this arrangement,
to improve its performance.
.PP
.bP
A call to \fBtgoto\fP using a capability with more than two parameters
is an error.
-.SH BUGS
-If you call \fBtgetstr\fP to fetch \fBca\fP 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\fP or \fBtparm\fP, which both expand
-terminfo-style strings as terminfo.
-(The \fBtgoto\fP 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,
-users can be surprised:
-.bP
-\fBtputs("50")\fP in a terminfo system will put out a literal \*(``50\*(''
-rather than busy-waiting for 50 milliseconds.
-.bP
-However, if ncurses is configured to support termcap,
-it may also have been configured to support the BSD-style padding.
-.IP
-In that case, \fBtputs\fP inspects strings passed to it,
-looking for digits at the beginning of the string.
-.IP
-\fBtputs("50")\fP in a termcap system may wait for 50 milliseconds
-rather than put out a literal \*(``50\*(''
-.PP
-Note that termcap has nothing analogous to terminfo's \fBsgr\fP string.
-One consequence of this is that termcap applications assume \fBme\fP
-(terminfo \fBsgr0\fP) 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,
the \fItermcap\fP 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.
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 BUGS
+If you call \fB\%tgetstr\fP to fetch \fB\%ca\fP or any other
+parameterized string capability,
+be aware that it is returned in \fI\%terminfo\fP notation,
+not the older and not-quite-compatible \fI\%termcap\fP notation.
+This does not cause problems if all you do with it is call \fB\%tgoto\fP
+or \fB\%tparm\fP, which both expand
+\fI\%terminfo\fP-style strings as \fI\%terminfo\fP does.
+(The \fB\%tgoto\fP function,
+if configured to support \fI\%termcap,\fP
+checks if the string is indeed \fI\%terminfo\fP-style by looking for
+\*(``\fB%p\fP\*('' parameters or \*(``\fB<\fP.\|.\|.\fB>\fP\*('' delays,
+and invokes a \fI\%termcap\fP-style parser if the string appears not to
+use \fI\%terminfo\fP syntax.)
+.PP
+Because \fI\%terminfo\fP's syntax for padding in string capabilities
+differs from \fI\%termcap\fP's,
+users can be surprised.
+.IP \(bu 4
+\fB\%tputs("50")\fP in a \fI\%terminfo\fP system transmits \*(``50\*(''
+rather than busy-waiting for 50 milliseconds.
+.IP \(bu 4
+However,
+if \fI\%ncurses\fP is configured to support \fI\%termcap\fP,
+it may also have been configured to support BSD-style padding.
+.IP
+In that case,
+\fB\%tputs\fP inspects strings passed to it,
+looking for digits at the beginning of the string.
+.IP
+\fB\%tputs("50")\fP in a \fI\%termcap\fP system may busy-wait for 50
+milliseconds rather than transmitting \*(``50\*(''.
+.PP
+\fI\%termcap\fP has nothing analogous to \fI\%terminfo\fP's \fBsgr\fP
+string.
+One consequence is that \fI\%termcap\fP applications assume that
+\fBme\fP
+(equivalent to \fI\%terminfo\fP's \fBsgr0\fP capability)
+does not reset the alternate character set.
+\fI\%ncurses\fP checks for,
+and modifies the data shared with,
+the \fI\%termcap\fP interface to accommodate the latter's limitation in
+this respect.
.SH SEE ALSO
-\fBcurses\fP(3X),
-\fBputc\fP(3),
-\fBterm_variables\fP(3X),
-\fBterminfo\fP(\*n).
-.sp
-https://invisible-island.net/ncurses/tctest.html
+\fB\%curses\fP(3X),
+\fB\%putc\fP(3),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(5)
+.PP
+https://invisible\-island.net/ncurses/tctest.html
projects / ncurses.git / blobdiff