Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 454 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man3/getch.3ncurses b/upstream/opensuse-tumbleweed/man3/getch.3ncurses
new file mode 100644
index 00000000..09260d79
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man3/getch.3ncurses
@@ -0,0 +1,454 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 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_getch.3x,v 1.78 2024/02/17 19:27:03 tom Exp $
+.TH getch 3NCURSES 2024-02-17 "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\%getch\fP,
+\fB\%wgetch\fP,
+\fB\%mvgetch\fP,
+\fB\%mvwgetch\fP,
+\fB\%ungetch\fP,
+\fB\%has_key\fP \-
+get (or push back) characters from \fIcurses\fR terminal keyboard
+.SH SYNOPSIS
+.nf
+.B #include <ncursesw/curses.h>
+.PP
+.B int getch(void);
+.B int wgetch(WINDOW *\fIwin\fP);
+.B int mvgetch(int \fIy\fP, int \fIx\fP);
+.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.PP
+.B int ungetch(int \fIch\fP);
+.PP
+\fI/* extension */\fP
+.B int has_key(int \fIch\fP);
+.fi
+.SH DESCRIPTION
+.SS "Reading Characters"
+The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read
+a character from the window.
+In no-delay mode, if no input is waiting, the value \fBERR\fP is returned.
+In delay mode, the program waits until the system
+passes text through to the program.
+Depending on the setting of \fBcbreak\fP,
+this is after one character (cbreak mode),
+or after the first newline (nocbreak mode).
+In half-delay mode,
+the program waits until a character is typed or the
+specified timeout has been reached.
+.PP
+If \fBecho\fP is enabled, and the window is not a pad,
+then the character will also be echoed into the
+designated window according to the following rules:
+.bP
+If the character is the current erase character, left arrow, or backspace,
+the cursor is moved one space to the left and that screen position is erased
+as if \fBdelch\fP had been called.
+.bP
+If the character value is any other \fBKEY_\fP define, the user is alerted
+with a \fBbeep\fP call.
+.bP
+If the character is a carriage-return,
+and if \fBnl\fP is enabled,
+it is translated to a line-feed after echoing.
+.bP
+Otherwise the character is simply output to the screen.
+.PP
+If the window is not a pad, and it has been moved or modified since the last
+call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character
+is read.
+.SS "Keypad Mode"
+If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for
+that function key is returned instead of the raw characters:
+.bP
+The predefined function
+keys are listed in \fB<curses.h>\fP as macros with values outside the range
+of 8-bit characters.
+Their names begin with \fBKEY_\fP.
+.bP
+Other (user-defined) function keys which may be defined
+using \fB\%define_key\fP(3NCURSES)
+have no names, but also are expected to have values outside the range of
+8-bit characters.
+.PP
+Thus, a variable
+intended to hold the return value of a function key must be of short size or
+larger.
+.PP
+When a character that could be the beginning of a function key is received
+(which, on modern terminals, means an escape character),
+\fBcurses\fP sets a timer.
+If the remainder of the sequence does not come in within the designated
+time, the character is passed through;
+otherwise, the function key value is returned.
+For this reason, many terminals experience a delay between the time
+a user presses the escape key and the escape is returned to the program.
+.PP
+In \fI\%ncurses\fP, the timer normally expires after
+the value in \fBESCDELAY\fP (see \fB\%curses_variables\fP(3NCURSES)).
+If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire;
+it is an infinite (or very large) value.
+Because function keys usually begin with an escape character,
+the terminal may appear to hang in notimeout mode after pressing the escape key
+until another key is pressed.
+.SS "Ungetting Characters"
+The \fBungetch\fP routine places \fIch\fP back onto the input queue to be
+returned by the next call to \fBwgetch\fP.
+There is just one input queue for all windows.
+.SS "Predefined Key Codes"
+The following special keys are defined in \fB<curses.h>\fP.
+.bP
+Except for the special case \fBKEY_RESIZE\fP,
+it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes.
+.bP
+Not all of these are necessarily supported on any particular terminal.
+.bP
+The naming convention may seem obscure, with some apparent
+misspellings (such as \*(``RSUME\*('' for \*(``resume\*('').
+The names correspond to the long terminfo capability names for the keys,
+and were defined long ago, in the 1980s.
+.PP
+.RS
+.TS
+tab(/) ;
+l l .
+\fBName\fP/\fBKey\fP \fBname\fP
+_
+KEY_BREAK/Break key
+KEY_DOWN/The four arrow keys ...
+KEY_UP
+KEY_LEFT
+KEY_RIGHT
+KEY_HOME/Home key (upward+left arrow)
+KEY_BACKSPACE/Backspace
+KEY_F0/T{
+Function keys; space for 64 keys is reserved.
+T}
+KEY_F(\fIn\fP)/T{
+For 0 \(<= \fIn\fP \(<= 63
+T}
+KEY_DL/Delete line
+KEY_IL/Insert line
+KEY_DC/Delete character
+KEY_IC/Insert char or enter insert mode
+KEY_EIC/Exit insert char mode
+KEY_CLEAR/Clear screen
+KEY_EOS/Clear to end of screen
+KEY_EOL/Clear to end of line
+KEY_SF/Scroll 1 line forward
+KEY_SR/Scroll 1 line backward (reverse)
+KEY_NPAGE/Next page
+KEY_PPAGE/Previous page
+KEY_STAB/Set tab
+KEY_CTAB/Clear tab
+KEY_CATAB/Clear all tabs
+KEY_ENTER/Enter or send
+KEY_SRESET/Soft (partial) reset
+KEY_RESET/Reset or hard reset
+KEY_PRINT/Print or copy
+KEY_LL/Home down or bottom (lower left)
+KEY_A1/Upper left of keypad
+KEY_A3/Upper right of keypad
+KEY_B2/Center of keypad
+KEY_C1/Lower left of keypad
+KEY_C3/Lower right of keypad
+KEY_BTAB/Back tab key
+KEY_BEG/Beg(inning) key
+KEY_CANCEL/Cancel key
+KEY_CLOSE/Close key
+KEY_COMMAND/Cmd (command) key
+KEY_COPY/Copy key
+KEY_CREATE/Create key
+KEY_END/End key
+KEY_EXIT/Exit key
+KEY_FIND/Find key
+KEY_HELP/Help key
+KEY_MARK/Mark key
+KEY_MESSAGE/Message key
+KEY_MOUSE/Mouse event occurred
+KEY_MOVE/Move key
+KEY_NEXT/Next object key
+KEY_OPEN/Open key
+KEY_OPTIONS/Options key
+KEY_PREVIOUS/Previous object key
+KEY_REDO/Redo key
+KEY_REFERENCE/Ref(erence) key
+KEY_REFRESH/Refresh key
+KEY_REPLACE/Replace key
+KEY_RESIZE/Screen resized
+KEY_RESTART/Restart key
+KEY_RESUME/Resume key
+KEY_SAVE/Save key
+KEY_SBEG/Shifted beginning key
+KEY_SCANCEL/Shifted cancel key
+KEY_SCOMMAND/Shifted command key
+KEY_SCOPY/Shifted copy key
+KEY_SCREATE/Shifted create key
+KEY_SDC/Shifted delete char key
+KEY_SDL/Shifted delete line key
+KEY_SELECT/Select key
+KEY_SEND/Shifted end key
+KEY_SEOL/Shifted clear line key
+KEY_SEXIT/Shifted exit key
+KEY_SFIND/Shifted find key
+KEY_SHELP/Shifted help key
+KEY_SHOME/Shifted home key
+KEY_SIC/Shifted insert key
+KEY_SLEFT/Shifted left arrow key
+KEY_SMESSAGE/Shifted message key
+KEY_SMOVE/Shifted move key
+KEY_SNEXT/Shifted next key
+KEY_SOPTIONS/Shifted options key
+KEY_SPREVIOUS/Shifted prev key
+KEY_SPRINT/Shifted print key
+KEY_SREDO/Shifted redo key
+KEY_SREPLACE/Shifted replace key
+KEY_SRIGHT/Shifted right arrow key
+KEY_SRSUME/Shifted resume key
+KEY_SSAVE/Shifted save key
+KEY_SSUSPEND/Shifted suspend key
+KEY_SUNDO/Shifted undo key
+KEY_SUSPEND/Suspend key
+KEY_UNDO/Undo key
+.TE
+.RE
+.PP
+Keypad is arranged like this:
+.PP
+.RS
+.TS
+allbox tab(/) ;
+c c c .
+\fBA1\fP/\fBup\fP/\fBA3\fP
+\fBleft\fP/\fBB2\fP/\fBright\fP
+\fBC1\fP/\fBdown\fP/\fBC3\fP
+.TE
+.RE
+.sp
+A few of these predefined values do \fInot\fP correspond to a real key:
+.bP
+.B KEY_RESIZE
+is returned when the \fBSIGWINCH\fP signal has been detected
+(see \fB\%initscr\fP(3NCURSES) and \fB\%resizeterm\fP(3NCURSES)).
+This code is returned whether or not \fBkeypad\fP has been enabled.
+.bP
+.B KEY_MOUSE
+is returned for mouse-events (see \fB\%mouse\fP(3NCURSES)).
+This code relies upon whether or not \fB\%keypad\fP(3NCURSES) has been enabled,
+because
+(e.g.,
+with \fBxterm\fP(1) mouse prototocol)
+\fI\%ncurses\fP must read escape sequences,
+just like a function key.
+.SS "Testing Key Codes"
+The \fBhas_key\fP routine takes a key-code value from the above list, and
+returns \fBTRUE\fP or \fBFALSE\fP according to whether
+the current terminal type recognizes a key with that value.
+.PP
+The library also supports these extensions:
+.RS 3
+.TP 5
+.B define_key
+defines a key-code for a given string (see \fB\%define_key\fP(3NCURSES)).
+.TP 5
+.B key_defined
+checks if there is a key-code defined for a given
+string (see \fB\%key_defined\fP(3NCURSES)).
+.RE
+.SH RETURN VALUE
+All routines return the integer \fBERR\fP upon failure and an integer value
+other than \fBERR\fP (\fBOK\fP in the case of \fBungetch\fP) upon successful
+completion.
+.RS 3
+.TP 5
+\fBungetch\fP
+returns \fBERR\fP
+if there is no more room in the FIFO.
+.TP
+\fBwgetch\fP
+returns \fBERR\fP
+.RS
+.bP
+if the window pointer is null, or
+.bP
+if its timeout expires without having any data, or
+.bP
+if the execution was interrupted by a signal (\fBerrno\fP will be set to
+\fBEINTR\fP).
+.RE
+.RE
+.PP
+Functions with a \*(``mv\*('' prefix first perform a cursor movement using
+\fBwmove\fP, and return an error if the position is outside the window,
+or if the window pointer is null.
+.SH NOTES
+Use of the escape key by a programmer for a single character function is
+discouraged, as it will cause a delay of up to one second while the
+keypad code looks for a following function-key sequence.
+.PP
+Some keys may be the same as commonly used control
+keys, e.g.,
+\fBKEY_ENTER\fP versus control/M,
+\fBKEY_BACKSPACE\fP versus control/H.
+Some curses implementations may differ according to whether they
+treat these control keys specially (and ignore the terminfo), or
+use the terminfo definitions.
+\fI\%ncurses\fP uses the terminfo definition.
+If it says that \fBKEY_ENTER\fP is control/M,
+\fBgetch\fP will return \fBKEY_ENTER\fP
+when you press control/M.
+.PP
+Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP
+key on the numeric keypad:
+.bP
+the terminal description lists the most useful keys,
+.bP
+the \fIEnter\fP key on the regular keyboard is already handled by
+the standard ASCII characters for carriage-return and line-feed,
+.bP
+depending on whether \fBnl\fP or \fBnonl\fP was called,
+pressing \*(``Enter\*('' on the regular keyboard
+may return either a carriage-return or line-feed, and finally
+.bP
+\*(``Enter or send\*('' is the standard description for this key.
+.PP
+When using \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP, or
+\fBmvwgetch\fP, nocbreak mode (\fBnocbreak\fP) and echo mode
+(\fBecho\fP) should not be used at the same time.
+Depending on the
+state of the tty driver when each character is typed, the program may
+produce undesirable results.
+.PP
+Note that \fBgetch\fP, \fBmvgetch\fP, and \fBmvwgetch\fP may be macros.
+.PP
+Historically, the set of keypad macros was largely defined by the extremely
+function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4.
+Modern
+personal computers usually have only a small subset of these.
+IBM PC-style
+consoles typically support little more than \fBKEY_UP\fP, \fBKEY_DOWN\fP,
+\fBKEY_LEFT\fP, \fBKEY_RIGHT\fP, \fBKEY_HOME\fP, \fBKEY_END\fP,
+\fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12.
+The Ins key
+is usually mapped to \fBKEY_IC\fP.
+.SH EXTENSIONS
+\fB\%has_key\fP was designed for \fB\%ncurses\fP(3NCURSES),
+and is not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
+.SH PORTABILITY
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.PP
+X/Open Curses, Issue 4, Version 2, describes
+\fB\%getch\fP,
+\fB\%wgetch\fP,
+\fB\%mvgetch\fP,
+\fB\%mvwgetch\fP,
+and
+\fB\%ungetch\fP.
+They read single-byte characters only.
+The standard specifies that they return \fBERR\fP on failure,
+but describes no failure conditions.
+.PP
+The echo behavior of these functions on input of
+.B KEY_
+or backspace characters was not specified in the SVr4 documentation.
+This description is adapted from X/Open Curses.
+.PP
+The behavior of \fBgetch\fP and friends in the presence of signal
+handlers is unspecified in the SVr4 documentation and X/Open Curses.
+Under historical curses implementations,
+it varied depending on whether the operating system's dispatch of a
+signal to a handler interrupts a \fBread\fP(2) call in progress or not,
+and also
+(in some implementations)
+whether an input timeout or non-blocking mode has been set.
+.PP
+.B KEY_MOUSE
+is mentioned in X/Open Curses,
+along with a few related
+.I \%term\%info
+capabilities,
+but no higher-level functions use the feature.
+The implementation in
+.I \%ncurses
+is an extension.
+.PP
+.B KEY_RESIZE
+is an extension first implemented for
+.I \%ncurses.
+NetBSD
+.I curses
+later added this extension.
+.PP
+Programmers concerned about portability should be prepared for either of two
+cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt
+interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to
+\fBEINTR\fP.
+.PP
+The \fBhas_key\fP function is unique to \fI\%ncurses\fP.
+We recommend that
+any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro.
+.SH SEE ALSO
+\fB\%ncurses\fP(3NCURSES),
+\fB\%inopts\fP(3NCURSES),
+\fB\%mouse\fP(3NCURSES),
+\fB\%move\fP(3NCURSES),
+\fB\%outopts\fP(3NCURSES),
+\fB\%refresh\fP(3NCURSES),
+\fB\%curses_variables\fP(3NCURSES),
+\fB\%resizeterm\fP(3NCURSES)
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fB\%get_wch\fP(3NCURSES).