Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 547 insertions, 0 deletions

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 <curses.h>
+\fB#include <term.h>
+.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 <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
+.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