.\"***************************************************************************
-.\" Copyright 2018-2022,2023 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_initscr.3x,v 1.60 2023/12/23 16:27:25 tom Exp $
-.TH curs_initscr 3X 2023-12-23 "ncurses 6.4" "Library calls"
+.\" $Id: curs_initscr.3x,v 1.73 2024/06/01 22:38:43 tom Exp $
+.TH curs_initscr 3X 2024-06-01 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
X/Open defines no error conditions.
In this implementation
.bP
-\fBendwin\fP returns an error if
+\fBendwin\fP returns
+.B ERR
+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.
+\fBreset_shell_mode\fP(3X) return
+.BR ERR "."
.RE
.bP
\fBnewterm\fP
-returns an error if it cannot allocate the data structures for the screen,
+returns
+.B ERR
+if it cannot allocate the data structures for the screen,
or for the top-level windows within the screen,
i.e.,
\fBcurscr\fP, \fBnewscr\fP, or \fBstdscr\fP.
\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,
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.
(\fIgn\fP) capability.
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.
+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
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
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 \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
+that is later tested by \fB\%wgetch\fP(3X) and \fB\%wget_wch\fP(3X):
+.RS
+.bP
+.B \%wgetch
+returns the key code
+.BR \%KEY_RESIZE "."
+.bP
+.B \%wget_wch
+returns
+.B \%KEY_CODE_YES
+and sets its
+.I wch
+parameter to
+.BR \%KEY_RESIZE "."
+.RE
+.IP
+At the same time, \fI\%ncurses\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