Adding upstream version 4.23.0.upstream/4.23.0

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

1 files changed, 123 insertions, 93 deletions

diff --git a/upstream/archlinux/man3/curs_initscr.3x b/upstream/archlinux/man3/curs_initscr.3x
index 5e17ead0..a90bfd5d 100644
--- a/upstream/archlinux/man3/curs_initscr.3x
+++ b/upstream/archlinux/man3/curs_initscr.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
+.\" 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  *
@@ -27,42 +27,44 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_initscr.3x,v 1.39 2022/07/24 15:46:49 tom Exp $
-.TH curs_initscr 3X ""
+.\" $Id: curs_initscr.3x,v 1.69 2024/04/20 21:24:19 tom Exp $
+.TH curs_initscr 3X 2024-04-20 "ncurses 6.5" "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
 ..
-.ie \n(.g .ds `` \(lq
-.el       .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el       .ds '' ''
-.na
-.hy 0
 .SH NAME
-\fBinitscr\fP,
-\fBnewterm\fP,
-\fBendwin\fP,
-\fBisendwin\fP,
-\fBset_term\fP,
-\fBdelscreen\fP \- \fBcurses\fP screen initialization and manipulation routines
-.ad
-.hy
+\fB\%initscr\fP,
+\fB\%newterm\fP,
+\fB\%endwin\fP,
+\fB\%isendwin\fP,
+\fB\%set_term\fP,
+\fB\%delscreen\fP \-
+initialize, manipulate, or tear down \fIcurses\fR terminal interface
 .SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBWINDOW *initscr(void);\fP
-.br
-\fBint endwin(void);\fP
-.sp
-\fBbool isendwin(void);\fP
-.sp
-\fBSCREEN *newterm(const char *\fItype\fB, FILE *\fIoutfd\fB, FILE *\fIinfd\fB);\fR
-.br
-\fBSCREEN *set_term(SCREEN *\fInew\fB);\fR
-.br
-\fBvoid delscreen(SCREEN* \fIsp\fB);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBWINDOW *initscr(void);
+\fBint endwin(void);
+.PP
+\fBbool isendwin(void);
+.PP
+\fBSCREEN *newterm(const char *\fItype\fP, FILE *\fIoutf\fP, FILE *\fIinf\fP);
+\fBSCREEN *set_term(SCREEN *\fInew\fP);
+\fBvoid delscreen(SCREEN* \fIsp\fP);
+.fi
 .SH DESCRIPTION
 .SS initscr
 \fBinitscr\fP is normally the first \fBcurses\fP routine to call when
@@ -81,27 +83,30 @@ If errors occur, \fBinitscr\fP writes an appropriate error
 message to standard error and exits;
 otherwise, a pointer is returned to \fBstdscr\fP.
 .SS newterm
-.PP
 A program that outputs to more than one terminal should use the \fBnewterm\fP
 routine for each terminal instead of \fBinitscr\fP.
 A program that needs to inspect capabilities,
 so it can continue to run in a line-oriented mode if the
 terminal cannot support a screen-oriented program, would also use
 \fBnewterm\fP.
+.PP
 The routine \fBnewterm\fP should be called once for each terminal.
-It returns a variable of type \fBSCREEN *\fP which should be saved
+It returns a variable of type \fISCREEN *\fP which should be saved
 as a reference to that terminal.
 \fBnewterm\fP's arguments are
 .bP
 the \fItype\fP of the terminal to be used in place of \fB$TERM\fP,
 .bP
-a file pointer for output to the terminal, and
+an output stream connected to the terminal, and
 .bP
-another file pointer for input from the terminal
+an input stream connected to the terminal
 .PP
 If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used.
-.SS endwin
 .PP
+The file descriptor of the output stream is passed to \fBsetupterm\fP(3X),
+which returns a pointer to a \fI\%TERMINAL\fP structure.
+\fBnewterm\fP's return value holds a pointer to the \fI\%TERMINAL\fP structure.
+.SS endwin
 The program must also call
 \fBendwin\fP for each terminal being used before exiting from \fBcurses\fP.
 If \fBnewterm\fP is called more than once for the same terminal, the first
@@ -126,24 +131,21 @@ restores tty modes (see \fBreset_shell_mode\fP(3X)).
 Calling \fBrefresh\fP(3X) or \fBdoupdate\fP(3X) after a
 temporary escape causes the program to resume visual mode.
 .SS isendwin
-.PP
 The \fBisendwin\fP routine returns \fBTRUE\fP if \fBendwin\fP has been
 called without any subsequent calls to \fBwrefresh\fP,
 and \fBFALSE\fP otherwise.
 .SS set_term
-.PP
 The \fBset_term\fP routine is used to switch between different terminals.
 The screen reference \fInew\fP becomes the new current terminal.
 The previous terminal is returned by the routine.
-This is the only routine which manipulates \fBSCREEN\fP pointers;
+This is the only routine which manipulates \fISCREEN\fP pointers;
 all other routines affect only the current terminal.
 .SS delscreen
-.PP
 The \fBdelscreen\fP routine frees storage associated with the
-\fBSCREEN\fP data structure.
+\fISCREEN\fP data structure.
 The \fBendwin\fP routine does not do
 this, so \fBdelscreen\fP should be called after \fBendwin\fP if a
-particular \fBSCREEN\fP is no longer needed.
+particular \fISCREEN\fP is no longer needed.
 .SH RETURN VALUE
 \fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP
 upon successful completion.
@@ -153,7 +155,15 @@ Routines that return pointers always return \fBNULL\fP on error.
 X/Open defines no error conditions.
 In this implementation
 .bP
-\fBendwin\fP returns an error if the terminal was not initialized.
+\fBendwin\fP returns an error if
+.RS
+.bP
+the terminal was not initialized, or
+.bP
+\fBendwin\fP is called more than once without updating the screen, or
+.bP
+\fBreset_shell_mode\fP(3X) returns an error.
+.RE
 .bP
 \fBnewterm\fP
 returns an error if it cannot allocate the data structures for the screen,
@@ -164,14 +174,14 @@ i.e.,
 \fBset_term\fP
 returns no error.
 .SH PORTABILITY
-These functions were described in the XSI Curses standard, Issue 4.
+These functions were described in X/Open Curses, Issue 4.
 As of 2015, the current document is X/Open Curses, Issue 7.
 .SS Differences
-X/Open specifies that portable applications must not
+X/Open Curses specifies that portable applications must not
 call \fBinitscr\fP more than once:
 .bP
 The portable way to use \fBinitscr\fP is once only,
-using \fBrefresh\fP (see curs_refresh(3X))
+using \fB\%refresh\fP(3X)
 to restore the screen after \fBendwin\fP.
 .bP
 This implementation allows using \fBinitscr\fP after \fBendwin\fP.
@@ -179,62 +189,81 @@ This implementation allows using \fBinitscr\fP after \fBendwin\fP.
 Old versions of curses, e.g., BSD 4.4, would return a null pointer
 from \fBinitscr\fP when an error is detected, rather than exiting.
 It is safe but redundant to check the return value of \fBinitscr\fP
-in XSI Curses.
+in X/Open Curses.
 .PP
 Calling \fBendwin\fP does not dispose of the memory allocated in \fBinitscr\fP
 or \fBnewterm\fP.
-Deleting a \fBSCREEN\fP provides a way to do this:
+Deleting a \fISCREEN\fP provides a way to do this:
 .bP
-X/Open Curses does not say what happens to \fBWINDOW\fPs when \fBdelscreen\fP
-\*(``frees storage associated with the \fBSCREEN\fP\*(''
+X/Open Curses does not say what happens to \fI\%WINDOW\fPs when \fBdelscreen\fP
+\*(``frees storage associated with the \fISCREEN\fP\*(''
 nor does the SVr4 documentation help,
-adding that it should be called after \fBendwin\fP if a \fBSCREEN\fP
+adding that it should be called after \fBendwin\fP if a \fISCREEN\fP
 is no longer needed.
 .bP
-However, \fBWINDOW\fPs are implicitly associated with a \fBSCREEN\fP.
+However, \fI\%WINDOW\fPs are implicitly associated with a \fISCREEN\fP.
 so that it is reasonable to expect \fBdelscreen\fP to deal with these.
 .bP
-SVr4 curses deletes the standard \fBWINDOW\fP structures
+SVr4 curses deletes the standard \fI\%WINDOW\fP structures
 \fBstdscr\fP and \fBcurscr\fP as well as a work area \fBnewscr\fP.
 SVr4 curses ignores other windows.
 .bP
-Since version 4.0 (1996), ncurses has maintained a list of all windows
-for each screen,
+Since version 4.0 (1996),
+\fI\%ncurses\fP has maintained a list of all windows for each screen,
 using that information to delete those windows when \fBdelscreen\fP is called.
 .bP
-NetBSD copied this feature of ncurses in 2001.
+NetBSD copied this feature of \fI\%ncurses\fP in 2001.
 PDCurses follows the SVr4 model,
-deleting only the standard \fBWINDOW\fP structures.
-.SS Unset TERM Variable
+deleting only the standard \fI\%WINDOW\fP structures.
+.SS "High-level versus Low-level"
+Different implementations may disagree regarding the level of some functions.
+For example, \fISCREEN\fP (returned by \fBnewterm\fP) and
+\fI\%TERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for
+the output stream.
+If an application switches screens using \fBset_term\fR,
+or switches terminals using \fBset_curterm\fP(3X),
+applications which use the output file descriptor can have different
+behavior depending on which structure holds the corresponding descriptor.
 .PP
-If the TERM variable is missing or empty, \fBinitscr\fP uses the
+For example
+.bP
+NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fI\%TERMINAL\fP.
+\fI\%ncurses\fP and SVr4 use the descriptor in \fISCREEN\fP.
+.bP
+NetBSD and \fI\%ncurses\fP use the descriptor
+in \fI\%TERMINAL\fP
+for terminal I/O modes,
+e.g.,
+\fBdef_shell_mode\fP(3X),
+\fBdef_prog_mode\fP(3X).
+SVr4 curses uses the descriptor in \fISCREEN\fP.
+.SS "Unset \fITERM\fP Variable"
+If the \fITERM\fP variable is missing or empty, \fBinitscr\fP uses the
 value \*(``unknown\*('',
 which normally corresponds to a terminal entry with the \fIgeneric\fP
 (\fIgn\fP) capability.
-Generic entries are detected by \fBsetupterm\fP
-(see curs_terminfo(3X)) and cannot be used for full-screen operation.
-Other implementations may handle a missing/empty TERM variable differently.
-.SS Signal Handlers
-.PP
-Quoting from X/Open Curses, section 3.1.1:
+Generic entries are detected by \fBsetupterm\fP(3X)
+and cannot be used for full-screen operation.
+Other implementations may handle
+a missing/empty \fITERM\fP variable differently.
+.SS "Signal Handlers"
+Quoting from X/Open Curses Issue 7, section 3.1.1:
 .RS 5
-.hy 0
 .PP
-.I Curses implementations may provide for special handling of the
-.I \fBSIGINT\fP,
-.I \fBSIGQUIT\fP and
-.I \fBSIGTSTP\fP signals
-.I if their disposition is \fBSIG_DFL\fP at the time
-\fBinitscr\fI is called \fR...
+Curses implementations may provide for special handling of the
+\%SIGINT,
+\%SIGQUIT,
+and \%SIGTSTP signals if their disposition is \%SIG_DFL at the time
+.I \%initscr
+is called.\|.\|.
 .PP
-.I Any special handling for these signals may remain in effect for the
-.I life of the process or until the process changes the disposition of
-.I the signal.
+Any special handling for these signals may remain in effect for the
+life of the process or until the process changes the disposition of
+the signal.
 .PP
-.I None of the Curses functions are required to be safe
-.I with respect to signals \fP...
+None of the Curses functions are required to be safe
+with respect to signals.\|.\|.
 .RE
-.hy
 .PP
 This implementation establishes signal handlers during initialization,
 e.g., \fBinitscr\fP or \fBnewterm\fP.
@@ -242,18 +271,19 @@ Applications which must handle these signals should set up the corresponding
 handlers \fIafter\fP initializing the library:
 .TP 5
 .B SIGINT
-The handler \fIattempts\fP to cleanup the screen on exit.
+The handler \fIattempts\fP to clean up the screen on exit.
 Although it \fIusually\fP works as expected, there are limitations:
 .RS 5
 .bP
-Walking the \fBSCREEN\fP list is unsafe, since all list management
+Walking the \fISCREEN\fP list is unsafe, since all list management
 is done without any signal blocking.
 .bP
 On systems which have \fBREENTRANT\fP turned on, \fBset_term\fP uses
 functions which could deadlock or misbehave in other ways.
 .bP
-\fBendwin\fP calls other functions, many of which use stdio or
-other library functions which are clearly unsafe.
+\fBendwin\fP calls other functions,
+many of which use \fI\%stdio\fP(3) or other library functions which are
+clearly unsafe.
 .RE
 .TP 5
 .B SIGTERM
@@ -264,26 +294,26 @@ purpose than \fBSIGQUIT\fP (which is used in debugging).
 .B SIGTSTP
 This handles the \fIstop\fP signal, used in job control.
 When resuming the process, this implementation discards pending
-input with \fBflushinput\fP (see curs_util(3X)), and repaints the screen
+input with \fB\%flushinp\fP(3X), and repaints the screen
 assuming that it has been completely altered.
-It also updates the saved terminal modes with \fBdef_shell_mode\fP
-(see \fBcurs_kernel\fP(3X)).
+It also updates the saved terminal modes with
+\fB\%def_shell_mode\fP(3X).
 .TP 5
 .B SIGWINCH
 This handles the window-size changes which were ignored in
 the standardization efforts.
 The handler sets a (signal-safe) variable
-which is later tested in \fBwgetch\fP (see curs_getch(3X)).
+which is later tested in \fB\%wgetch\fP(3X).
 If \fBkeypad\fP has been enabled for the corresponding window,
 \fBwgetch\fP returns the key symbol \fBKEY_RESIZE\fP.
 At the same time, \fBwgetch\fP calls \fBresizeterm\fP to adjust the
 standard screen \fBstdscr\fP,
 and update other data such as \fBLINES\fP and \fBCOLS\fP.
 .SH SEE ALSO
-\fBcurses\fP(3X),
-\fBcurs_kernel\fP(3X),
-\fBcurs_refresh\fP(3X),
-\fBcurs_slk\fP(3X),
-\fBcurs_terminfo\fP(3X),
-\fBcurs_util\fP(3X),
-\fBcurs_variables\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_slk\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_util\fP(3X),
+\fB\%curs_variables\fP(3X)