X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_termcap.3x;h=5a85467b14e200af4fcabd6685457ddf28e6a3a6;hp=7cf547d58d1b0cc608a02deb3214241addbf6060;hb=HEAD;hpb=e5d1530ca229aef94a3c84ad33f8ae89f35c4045 diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x index 7cf547d5..6bd2a66a 100644 --- a/man/curs_termcap.3x +++ b/man/curs_termcap.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" 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 * @@ -27,312 +27,521 @@ .\" 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 \fR -.br -\fB#include \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 +\fB#include .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 . +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