.\"***************************************************************************
-.\" Copyright 2018-2022,2022 Thomas E. Dickey *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey *
.\" Copyright 1998-2017,2018 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.56 2022/02/12 20:05:11 tom Exp $
-.TH curs_termcap 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_termcap.3x,v 1.70 2023/10/14 19:26:28 tom Exp $
+.TH curs_termcap 3X 2023-10-14 "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,
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).
+In that case, \fBtgoto\fP uses an internal version of
+\fBtparm\fP(3X) (a more capable formatter).
+.IP
+With terminfo support, \fBtgoto\fP is able to use some of the terminfo
+features, but not all.
+In particular, it allows only numeric parameters;
+\fBtparm\fP supports string parameters.
.IP
However, \fBtparm\fP is not a \fItermcap\fP feature,
and portable \fItermcap\fP applications should not rely upon its availability.
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.
completion.
.PP
Routines that return pointers return \fBNULL\fP on 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:
+A few special cases apply:
.bP
-\fBtputs("50")\fP in a terminfo system will put out a literal \*(``50\*(''
-rather than busy-waiting for 50 milliseconds.
+If the terminal database has not been initialized,
+these return an error.
.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.
+The calls with a string parameter (\fBtgoto\fP, \fBtputs\fP)
+check if the string is null, or cancelled.
+Those return an error.
+.bP
+A call to \fBtgoto\fP using a capability with string parameters is an error.
+.bP
+A call to \fBtgoto\fP using a capability with more than two parameters
+is an error.
.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(\*n)
+.PP
+https://invisible\-island.net/ncurses/tctest.html