+.\"***************************************************************************
+.\" 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.52 2021/12/25 21:31:00 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
-\fBtgetent\fR, \fBtgetflag\fR, \fBtgetnum\fR,
-\fBtgetstr\fR, \fBtgoto\fR, \fBtputs\fR - direct \fBcurses\fR
-interface to the terminfo capability database
+\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
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+\fB#include <curses.h>\fP
.br
-\fB#include <term.h>\fR
+\fB#include <term.h>\fP
+.sp
+\fBextern char PC;\fP
.br
-\fBint tgetent(const char *bp, char *name);\fR
+\fBextern char * UP;\fP
.br
-\fBint tgetflag(const char *id);\fR
+\fBextern char * BC;\fP
.br
-\fBint tgetnum(const char *id);\fR
+\fBextern @NCURSES_OSPEED@ ospeed;\fP
+.sp
+\fBint tgetent(char *\fP\fIbp\fP\fB, const char *\fP\fIname\fP\fB);\fP
.br
-\fBchar *tgetstr(const char *id, char **area);\fR
+\fBint tgetflag(const char *\fP\fIid\fP\fB);\fP
.br
-\fBchar *tgoto(const char *cap, int col, int row);\fR
+\fBint tgetnum(const char *\fP\fIid\fP\fB);\fP
.br
-\fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR
+\fBchar *tgetstr(const char *\fP\fIid\fP\fB, char **\fP\fIarea\fP\fB);\fP
+.br
+\fBchar *tgoto(const char *\fP\fIcap\fP\fB, int \fP\fIcol\fP\fB, int \fP\fIrow\fP\fB);\fP
+.br
+\fBint tputs(const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
.br
.SH DESCRIPTION
These routines are included as a conversion aid for programs that use
-the \fItermcap\fR library. Their parameters are the same and the
-routines are emulated using the \fIterminfo\fR database. Thus, they
+the \fItermcap\fP library.
+Their parameters are the same, but the
+routines are emulated using the \fIterminfo\fP database.
+Thus, they
can only be used to query the capabilities of entries for which a
terminfo entry has been compiled.
-
-The \fBtgetent\fR routine loads the entry for \fIname\fR.
-It returns 1 on success, 0 if there is no such entry, and -1 if the
-terminfo database could not be found.
-The emulation ignores the buffer pointer \fIbp\fR.
-
-The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR.
-
-The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR.
-
-The \fBtgetstr\fR routine returns the string entry for \fIid\fR. Use
-\fBtputs\fR to output the returned string.
-
-The \fBtgoto\fR routine instantiates the parameters into the given capability.
-The output from this routine is to be passed to \fBtputs\fR.
-
-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 INITIALIZATION
+.PP
+The \fBtgetent\fP routine loads the entry for \fIname\fP.
+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\fP.
+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\fP routine gets the boolean entry for \fIid\fP,
+or zero if it is not available.
+.PP
+The \fBtgetnum\fP routine gets the numeric entry for \fIid\fP,
+or \-1 if it is not available.
+.PP
+The \fBtgetstr\fP routine returns the string entry for \fIid\fP,
+or zero if it is not available.
+Use \fBtputs\fP 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\fP,
+and the \fIarea\fP 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\fP parameter of
+\fBtgetflag\fP,
+\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,
+the output of \fBtgoto\fP should be passed to \fBtputs\fP
+rather than some other output function such as \fBprintf\fP(3).
+.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\fP routine is described on the \fBcurs_terminfo\fP(3X) manual
+page.
+It can retrieve capabilities by either termcap or terminfo name.
+.SS GLOBAL VARIABLES
+.PP
+The variables
+\fBPC\fP,
+\fBUP\fP and
+\fBBC\fP
+are set by \fBtgetent\fP to the terminfo entry's data for
+\fBpad_char\fP,
+\fBcursor_up\fP and
+\fBbackspace_if_not_bs\fP,
+respectively.
+\fBUP\fP is not used by ncurses.
+\fBPC\fP is used in the \fBtdelay_output\fP function.
+\fBBC\fP is used in the \fBtgoto\fP emulation.
+The variable \fBospeed\fP 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
+routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
+(SVr4 only specifies "an integer value other than \fBERR\fP") upon successful
completion.
-
-Routines that return pointers return \fBNULL\fR on error.
+.PP
+Routines that return pointers return \fBNULL\fP on error.
.SH BUGS
-If you call \fBtgetstr\fR to fetch \fBca\fR or any other parameterized string,
+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 won't cause problems if all
-you do with it is call \fBtgoto\fR or \fBtparm\fR, which both expand
-terminfo-style.
-
+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, \fBtputs("50");\fR will put out a literal "50" rather
-than busy-waiting for 50 milliseconds. Cope with it.
+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
-The XSI Curses standard, Issue 4 describes these functions. However, they
+.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
+values of \fBtgetent\fP 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\fP returns \fBOK\fP or \fBERR\fP.
+Because the purpose of these functions is to provide compatibility with
+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.
+In particular, some applications are reported to declare and/or
+modify \fBospeed\fP.
+.PP
+The comment that only the first two characters of the \fBid\fP 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 \fBjove\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 \fBreadline\fP(3) library.
+.PP
+A termcap.h file was provided in ncurses 1.8.1 (November 1993).
+That reflected influence by \fBemacs\fP(1) (rather than \fBjove\fP(1))
+and GNU termcap:
+.bP
+it provided declarations for a few global symbols used by \fBemacs\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), \fBterminfo\fR(\*n), \fBputc\fR(3S).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fP(3X),
+\fBputc\fP(3),
+\fBterm_variables\fP(3X),
+\fBterminfo\fP(\*n).
+.sp
+https://invisible-island.net/ncurses/tctest.html
projects / ncurses.git / blobdiff