From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/mageia-cauldron/man3/curs_termcap.3x | 547 ++++++++++++++++++++++++++ 1 file changed, 547 insertions(+) create mode 100644 upstream/mageia-cauldron/man3/curs_termcap.3x (limited to 'upstream/mageia-cauldron/man3/curs_termcap.3x') diff --git a/upstream/mageia-cauldron/man3/curs_termcap.3x b/upstream/mageia-cauldron/man3/curs_termcap.3x new file mode 100644 index 00000000..721892d2 --- /dev/null +++ b/upstream/mageia-cauldron/man3/curs_termcap.3x @@ -0,0 +1,547 @@ +.\"*************************************************************************** +.\" 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 * +.\" 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.81 2023/12/30 21:27:22 tom Exp $ +.TH curs_termcap 3X 2023-12-30 "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 +.. +. +.SH NAME +\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 +.nf +\fB#include +\fB#include +.PP +\fBchar PC; +\fBchar * UP; +\fBchar * BC; +\fBunsigned 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 5 \" "-1" + 2n + adjust for PDF +1 +on success, +.TP +0 +if there is no such entry +(or if the matching entry describes a generic terminal, +having too little information for +.I curses +applications to run), +and +.TP +\-1 +if the \fI\%term\%info\fP database could not be found. +.RE +.PP +This implementation differs from those of historical \fItermcap\fP +libraries. +.RS 3 +.bP +.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. +\fI\%ncurses\fP stores terminal type descriptions in compiled form, +which is not the same thing. +.bP +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 "Retrieving Capability Values" +\fB\%tgetflag\fP reports the Boolean entry for \fIid\fP, +or zero if it is not available. +.PP +\fB\%tgetnum\fP obtains the numeric entry for \fIid\fP, +or \-1 if it is not available. +.PP +\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, +\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, +\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 type description +loaded into memory. +.RE +.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 +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 \fB\%tgoto\fP is assumed to be used for the two-parameter +cursor positioning capability, +\fItermcap\fP applications also use it for single-parameter +capabilities. +.IP +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 \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 +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\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\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 +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 +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 +\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 +.bP +X/Open Curses, Issue 4, Version 2 (1996), +describes these functions, +marking them as +\*(``TO BE WITHDRAWN\*(''. +.bP +X/Open Curses, Issue 7 (2009) marks the \fItermcap\fP interface +(along with \fB\%vwprintw\fP and \fB\%vwscanw\fP) as withdrawn. +.PP +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\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 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 +.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 \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 "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 +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 \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 +(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 \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 +GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP(1) in mid-1993 to +support the \fI\%readline\fP(3) library. +.PP +\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 +global symbols used by \fIemacs\fP, +.bP +\fIconst\fP-qualified function prototypes, +and +.bP +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 expand \fI\%term\%info\fP-style strings 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 +https://invisible\-island.net/ncurses/tctest.html -- cgit v1.2.3