.\"***************************************************************************
-.\" Copyright 2018-2019,2020 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 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.44 2020/05/17 01:20:13 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.85 2024/04/20 19:13:12 tom Exp $
+.TH curs_termcap 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "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\fR,
-\fBUP\fR,
-\fBBC\fR,
-\fBospeed\fR,
-\fBtgetent\fR,
-\fBtgetflag\fR,
-\fBtgetnum\fR,
-\fBtgetstr\fR,
-\fBtgoto\fR,
-\fBtputs\fR \- direct \fBcurses\fR interface to the terminfo capability database
-.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>\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 *bp, const char *name);\fR
-.br
-\fBint tgetflag(const char *id);\fR
-.br
-\fBint tgetnum(const char *id);\fR
-.br
-\fBchar *tgetstr(const char *id, char **area);\fR
-.br
-\fBchar *tgoto(const char *cap, int col, int row);\fR
-.br
-\fBint tputs(const char *str, int affcnt, int (*putc)(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 and 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
+.nf
+\fB#include <curses.h>
+\fB#include <term.h>
.PP
-The \fBtgetent\fR routine loads the entry for \fIname\fR.
-It returns:
+\fBchar PC;
+\fBchar * UP;
+\fBchar * BC;
+\fB@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
+.I \%ncurses
+provides the foregoing variables and functions as a compatibility layer
+for programs that use the \fItermcap\fP library.
+The API is the same,
+but behavior is emulated using the \fI\%term\%info\fP database.
+Thus,
+it can be used only to query the capabilities of terminal database
+entries for which a \fI\%term\%info\fP entry has been compiled.
+.SS Initialization
+\fB\%tgetent\fP loads the terminal database entry for \fIname\fP;
+see \fBterm\fP(7).
+This must be done before calling any of the other functions.
+It returns
.RS 3
-.TP 3
+.TP 5 \" "-1" + 2n + adjust for PDF
1
on success,
-.TP 3
+.TP
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
+(or if the matching entry describes a generic terminal,
+having too little information for
+.I curses
+applications to run),
+and
+.TP
\-1
-if the terminfo database could not be found.
+if the \fI\%term\%info\fP database could not be found.
.RE
.PP
-This differs from the \fItermcap\fP library in two ways:
+This implementation differs from those of historical \fItermcap\fP
+libraries.
.RS 3
.bP
-The emulation ignores the buffer pointer \fIbp\fR.
-The \fItermcap\fP library would store a copy of the terminal
+.I \%ncurses
+ignores the buffer pointer \fIbp\fP,
+as do other \fItermcap\fP implementations conforming to portions of
+X/Open Curses now withdrawn.
+The BSD \fItermcap\fP library would store a copy of the terminal type
description in the area referenced by this pointer.
-However, ncurses stores its terminal descriptions in compiled
-binary form, which is not the same thing.
+\fI\%term\%info\fP stores terminal type descriptions in compiled 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.
+The meanings of the return values differ.
+The BSD \fItermcap\fP library does not check whether the terminal type
+description includes the
+.B \%generic
+.RB ( gn )
+capability,
+nor whether the terminal type description supports an addressable
+cursor,
+a property essential for any \fIcurses\fP implementation to operate.
.RE
-.SS CAPABILITY VALUES
-.PP
-The \fBtgetflag\fR routine gets the boolean entry for \fIid\fR,
+.SS "Retrieving Capability Values"
+\fB\%tgetflag\fP reports the Boolean entry for \fIid\fP,
or zero if it is not available.
.PP
-The \fBtgetnum\fR routine gets the numeric entry for \fIid\fR,
+\fB\%tgetnum\fP obtains the numeric entry for \fIid\fP,
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:
+\fB\%tgetstr\fP returns the string entry for \fIid\fP,
+or
+.B NULL
+if it is not available.
+Use \fB\%tputs\fP to output the string returned.
+The
+.I area
+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.
+However,
+\fI\%ncurses\fP checks to ensure that
+.I area
+is not
+.BR NULL ,
+and also that the resulting buffer pointer is not
+.BR NULL .
+If either check fails,
+.I area
+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.
+If the checks succeed,
+\fI\%ncurses\fP also copies the return value to the buffer pointed to by
+\fIarea\fP,
+and the library updates
+.I area
+to point past the null character terminating this value.
.bP
-The return value itself is an address in the terminal description which
-is loaded into memory.
+The return value itself is an address in the terminal type description
+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.
+.SS "Applying String Capabilities"
+String capabilities can be parameterized;
+see subsection \*(``Parameterized Strings\*('' in \fB\%terminfo\fP(5).
+\fB\%tgoto\fP applies its second and third arguments to the parametric
+placeholders in the capability stored in the first argument.
.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.
+The capability may contain padding specifications;
+see subsection \*(``Delays and Padding\*('' of \fB\%terminfo\fP(5).
+The output of \fB\%tgoto\fP should thus be passed to \fB\%tputs\fP
+rather than some other output function such as \fI\%printf\fP(3).
.bP
-While \fBtgoto\fP is assumed to be used for the two-parameter
+While \fB\%tgoto\fP is assumed to be used for the two-parameter
cursor positioning capability,
-termcap applications also use it for single-parameter capabilities.
+\fItermcap\fP 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.
+Doing so reveals a quirk in \fB\%tgoto\fP:
+most hardware terminals use cursor addressing with \fIrow\fP first,
+but the original developers of the \fItermcap\fP interface chose to
+put the \fIcol\fP (column) parameter first.
+The \fB\%tgoto\fP function swaps the order of its parameters.
+It does this even 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).
+Normally the \fI\%ncurses\fP library is compiled without
+full \fI\%termcap\fP support.
+In that case,
+\fB\%tgoto\fP uses an internal version of \fB\%tparm\fP(3X)
+(a more capable function).
.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
+Because it uses \fB\%tparm\fP internally,
+\fB\%tgoto\fP is able to use some \fI\%term\%info\fP features,
+but not all.
+In particular,
+it allows only numeric parameters;
+\fB\%tparm\fP supports string parameters.
+.IP
+However,
+\fB\%tparm\fP is not a \fItermcap\fP feature,
+and portable \fItermcap\fP applications should not rely upon its
+availability.
.PP
+\fB\%tputs\fP is described in \fB\%curs_terminfo\fP(3X).
+It can retrieve capabilities by either \fItermcap\fP or
+\fI\%term\%info\fP code.
+.SS "Global Variables"
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,
+\fBPC\fP,
+\fBUP\fP and
+\fBBC\fP
+are set by \fB\%tgetent\fP to the \fI\%term\%info\fP entry's data for
+\fB\%pad_char\fP,
+\fB\%cursor_up\fP and
+\fB\%backspace_if_not_bs\fP,
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.
+\fBUP\fP is not used by \fI\%ncurses\fP.
+\fBPC\fP is used by \fB\%delay_output\fP(3X).
+\fBBC\fP is used by \fB\%tgoto\fP emulation.
+The variable \fB\%ospeed\fP is set by \fI\%ncurses\fP using a
+system-specific encoding to indicate the terminal's data rate.
+.SS "Releasing Memory"
+The \fItermcap\fP functions provide no means of freeing memory,
+because legacy \fItermcap\fP implementations used only the buffer
+areas provided by the caller via \fB\%tgetent\fP and \fB\%tgetstr\fP.
+Those buffers are unused in \fI\%term\%info\fP.
.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).
+By contrast,
+\fI\%term\%info\fP allocates memory.
+It uses \fB\%setupterm\fP(3X) to obtain the data used by \fB\%tgetent\fP
+and the functions that retrieve capability values.
+One could use
+.RS
+.EX
+del_curterm(cur_term);
+.EE
+.RE
+to free this memory,
+but there is an additional complication with \fI\%ncurses\fP.
+It uses a fixed-size pool of storage locations,
+one per value of the terminal name parameter given to \fB\%tgetent\fP.
+The \fIscreen\fP(1) program relies upon this arrangement to improve its
+performance.
.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.
+An application that uses only the \fItermcap\fP functions,
+not the higher level
+.I \%curses
+API,
+could release the memory using \fB\%del_curterm\fP(3X),
+because the pool is freed using other functions;
+see \fB\%curs_memleaks\fP(3X).
+.SH "RETURN VALUE"
+The return values of
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetname\fP,
+and
+\fB\%tgetstr\fP
+are documented above.
.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.
+\fB\%tgoto\fP returns
+.B NULL
+on error.
+Error conditions include:
+.bP
+uninitialized state
+(\fB\%tgetent\fP was not called successfully),
+.bP
+.I cap
+being a null pointer,
+.bP
+.I cap
+referring to a canceled capability,
+.bP
+.I cap
+being a capability with string-valued parameters
+(a \fI\%term\%info\fP-only feature),
+and
+.bP
+.I cap
+being a capability with more than two parameters.
+.PP
+See \fB\%curs_terminfo\fP(3X) regarding \fB\%tputs\fP.
+.SH NOTES
+\fI\%ncurses\fP compares only the first two characters of the \fIid\fP
+parameter of
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetstr\fP to the capability names in the database.
.SH PORTABILITY
+These functions are no longer standardized
+(and the variables never were);
+\fI\%ncurses\fP provides them to support legacy applications.
+They should not be used in new programs.
.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.
+X/Open Curses, Issue 4, Version 2 (1996),
+describes these functions,
+marking them as
+\*(``TO BE WITHDRAWN\*(''.
.bP
-X/Open Curses, Issue 5 (December 2007) marked the termcap interface
-(along with \fBvwprintw\fP and \fBvwscanw\fP) as withdrawn.
+X/Open Curses, Issue 7 (2009) marks the \fItermcap\fP interface
+(along with \fB\%vwprintw\fP and \fB\%vwscanw\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.
+Neither X/Open Curses nor the SVr4 man pages documented the return
+values of \fB\%tgetent\fP correctly,
+though all three shown here were in fact returned ever since SVr1.
+In particular,
+an omission in the X/Open Curses specification has been misinterpreted
+to mean that \fB\%tgetent\fP returns \fBOK\fP or \fBERR\fP.
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.
+the \fItermcap\fP library,
+that is a defect in X/Open Curses, Issue 4, Version 2
+rather than in \fI\%ncurses\fP.
+.SS "Compatibility with BSD \fItermcap\fP"
+Externally visible variables are provided for support of certain
+\fItermcap\fP applications.
+However,
+their correct usage is poorly documented;
+for example,
+it is unclear when reading and writing them is meaningful.
+In particular,
+some applications are reported to declare and/or modify \fB\%ospeed\fP.
.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:
+The constraint that only the first two characters of the \fIid\fP
+parameter are used escapes many application developers.
+The BSD \fItermcap\fP library did not require a trailing null character
+on the capability identifier passed to \fB\%tgetstr\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetflag\fP.
+.\" See <https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/\
+.\" termlib/termcap.c>.
+Some applications thus assume that the \fItermcap\fP interface does not
+require the trailing null character for the capability identifier.
.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.
+.I \%ncurses
+disallows matches by the \fItermcap\fP interface against extended
+capability names that are longer than two characters;
+see \fB\%user_caps\fP(5).
.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.
+The BSD \fItermcap\fP function \fB\%tgetent\fP returns the text of a
+\fItermcap\fP entry in the buffer passed as an argument.
+This library,
+like other \fI\%term\%info\fP implementations,
+does not store terminal type 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.
+.SS "Header File"
+This library includes a \fI\%termcap.h\fP header for compatibility with
+other implementations,
+but the header is rarely used because the other implementations are not
+strictly compatible.
+.SH HISTORY
+.\" See https://www.oreilly.com/openbook/opensources/book/kirkmck.html
+.\" for much BSD release history.
+Bill Joy originated a forerunner of \fItermcap\fP called
+\*(``ttycap\*('',
+dated September 1977,
+and released in 1BSD
+(March 1978).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s7/ttycap.c
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
+It used many of the same function names as the later \fItermcap\fP,
+such as
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetstr\fP.
+.PP
+A clear descendant,
+the \fItermlib\fP library,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/termlib/
+followed in 2BSD
+(May 1979),
+adding \fB\%tgoto\fP and \fB\%tputs\fP.
+The former applied at that time only to cursor positioning capabilities,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/bin/etc/termcap
+thus the overly specific name.
+Little changed in 3BSD
+(late 1979)
+except the addition of test programs and a \fI\%termlib\fP man page,
+which documented the API shown in section \*(``SYNOPSIS\*('' above.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/lib/\
+.\" libtermlib/
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/man/man3/\
+.\" termlib.3
.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:
+4BSD
+(November 1980)
+renamed \fItermlib\fP to \fItermcap\fP
+.\" ...except in the source tree...
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\" libtermlib/makefile
+and added another test program.
+The library remained much the same though 4.3BSD
+(June 1986).
+4.4BSD-Lite
+(June 1994)
+refactored it,
+.\" Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()`
+.\" entry points disappearing from termcap.c.
+leaving the API unchanged.
+.PP
+Function prototypes were a feature of ANSI C (1989).
+The library long antedated the standard and thus provided no header file
+declaring them.
+Nevertheless,
+the BSD sources included two different \fI\%termcap.h\fP header files
+over time.
.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.
+One was used internally by \fBjove\fP(1) from 4.3BSD onward.
+.\" 2BSD became a branch retaining support for non-virtual memory
+.\" systems (such as the PDP-11) whereas most BSD development focused on
+.\" the VAX and other VM-enabled systems starting with 3BSD.
+.\"
+.\" This man page previously located a termcap.h in 2BSD, but that may
+.\" be confusion arising from its backport to 2.9BSD (and still present
+.\" in surviving sources for 2.11BSD, the "end of the line" for that
+.\" branch's development).
+.\"
+.\" Observe the copyright notice in
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/contrib/\
+.\" jove/Makefile
+.\" --much too late for 2BSD (1979).
+It declared global symbols for the \fItermcap\fP variables that 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.
+The other appeared in 4.4BSD-Lite Release 2
+(June 1995)
+as part of \fIlibedit\fP
+(also known as the \fI\%edit\%line\fP library).
+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 \fI\%edit\%line\fP library.
+It declared function prototypes,
+but no global variables.
+This header file was added to NetBSD's \fItermcap\fP 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.
+Meanwhile,
+GNU \fItermcap\fP began development in 1990.
+Its first release (1.0) in 1991 included a \fI\%termcap.h\fP header.
+Its second (1.1) in September 1992 modified the header to use
+\fIconst\fP for the function prototypes in the header where one would
+expect the parameters to be read-only.
+BSD \fItermcap\fP did not.
+The prototype for \fB\%tputs\fP also differed,
+but in that instance,
+it was \fIlibedit\fP that differed from BSD \fItermcap\fP.
.PP
-A copy of GNU termcap 1.3 was bundled with \fIbash\fP in mid-1993,
-to support the \fIreadline\fP library.
+GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP(1) in mid-1993 to
+support the \fI\%readline\fP(3) 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:
+\fI\%ncurses\fP 1.8.1
+(November 1993)
+provided a \fI\%termcap.h\fP file.
+It reflected influence from GNU \fItermcap\fP and \fBemacs\fP(1)
+(rather than \fBjove\fP(1)),
+providing the following interface:
.bP
-it provided declarations for a few global symbols used by \fIemacs\fP
+global symbols used by \fIemacs\fP,
.bP
-it provided function prototypes (using \fBconst\fP).
+\fIconst\fP-qualified function prototypes,
+and
.bP
-a prototype for \fBtparam\fP (a GNU termcap feature) was provided.
+a prototype for \fBtparam\fP,
+a GNU \fItermcap\fP feature.
+.PP
+Later
+(in mid-1996)
+the \fB\%tparam\fP function was removed from \fI\%ncurses\fP.
+Any two of the four implementations thus differ,
+and programs that intend to work with all \fItermcap\fP library
+interfaces must account for that fact.
+.SH BUGS
+If you call \fB\%tgetstr\fP to fetch
+.B \%column_address
+.RB ( ch )
+or any other parameterized string capability,
+be aware that it is returned in \fI\%term\%info\fP notation,
+not the older and not-quite-compatible \fItermcap\fP notation.
+This does not cause problems if all you do with it is call \fB\%tgoto\fP
+or \fB\%tparm\fP,
+which both parametrically expand \fI\%term\%info\fP-style string
+capabilities as \fI\%term\%info\fP does.
+(If
+.I \%ncurses
+is configured to support \fItermcap,\fP
+\fB\%tgoto\fP checks whether the string is \fI\%term\%info\fP-style by
+looking for \*(``\fB%p\fP\*('' parameters or
+\*(``\fB<\fP.\|.\|.\fB>\fP\*('' delays,
+and invokes a \fItermcap\fP-style parser if the string appears not to
+use \fI\%term\%info\fP syntax.)
+.PP
+Because \fI\%term\%info\fP's syntax for padding in string capabilities
+differs from \fItermcap\fP's,
+users can be surprised.
+.IP \(bu 4
+\fB\%tputs("50")\fP in a \fI\%term\%info\fP system transmits
+\*(``50\*('' rather than busy-waiting for 50 milliseconds.
+.IP \(bu 4
+However,
+if \fI\%ncurses\fP is configured to support \fItermcap\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 \fItermcap\fP system may busy-wait for 50
+milliseconds rather than transmitting \*(``50\*(''.
+.PP
+\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's
+.B \%set_attributes
+.RB ( sgr )
+capability.
+One consequence is that \fItermcap\fP applications assume that
+.RB \*(`` me \*(''
+(equivalent to \fI\%term\%info\fP's
+.B \%exit_attribute_mode
+.RB ( sgr0 )
+capability)
+does not reset the alternate character set.
+\fI\%ncurses\fP checks for,
+and modifies the data shared with,
+the \fItermcap\fP interface to accommodate the latter's limitation in
+this respect.
+.SH "SEE ALSO"
+\fB\%curses\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%putc\fP(3),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(5)
.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),
-\fBterm_variables\fR(3X),
-\fBputc\fR(3).
-.sp
-https://invisible-island.net/ncurses/tctest.html
+https://invisible\-island.net/ncurses/tctest.html
projects / ncurses.git / blobdiff