+.\"***************************************************************************
+.\" Copyright 2018-2020,2021 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_initscr.3x,v 1.36 2021/12/25 21:41:58 tom Exp $
.TH curs_initscr 3X ""
+.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\fR, \fBnewterm\fR, \fBendwin\fR,
-\fBisendwin\fR, \fBset_term\fR, \fBdelscreen\fR - \fBcurses\fR screen
-initialization and manipulation routines
+\fBinitscr\fP,
+\fBnewterm\fP,
+\fBendwin\fP,
+\fBisendwin\fP,
+\fBset_term\fP,
+\fBdelscreen\fP \- \fBcurses\fP screen initialization and manipulation routines
+.ad
+.hy
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-
-\fBWINDOW *initscr(void);\fR
+\fB#include <curses.h>\fP
+.sp
+\fBWINDOW *initscr(void);\fP
.br
-\fBint endwin(void);\fR
+\fBint endwin(void);\fP
+.sp
+\fBbool isendwin(void);\fP
+.sp
+\fBSCREEN *newterm(const char *\fP\fItype\fP\fB, FILE *\fP\fIoutfd\fP\fB, FILE *\fP\fIinfd\fP\fB);\fP
.br
-\fBint isendwin(void);\fR
+\fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fP
.br
-\fBSCREEN *newterm(const char *type, FILE *outfd, FILE *infd);\fR
-.br
-\fBSCREEN *set_term(SCREEN *new);\fR
-.br
-\fBvoid delscreen(SCREEN* sp);\fR
+\fBvoid delscreen(SCREEN* \fP\fIsp\fP\fB);\fP
.br
.SH DESCRIPTION
-\fBinitscr\fR is normally the first \fBcurses\fR routine to call when
-initializing a program. A few special routines sometimes need to be
-called before it; these are \fBslk_init\fR, \fBfilter\fR, \fBripoffline\fR,
-\fBuse_env\fR. For multiple-terminal applications, \fBnewterm\fR may be
-called before \fBinitscr\fR.
-
-The initscr code determines the terminal type and initializes all \fBcurses\fR
-data structures. \fBinitscr\fR also causes the first call to \fBrefresh\fR to
-clear the screen. If errors occur, \fBinitscr\fR writes an appropriate error
-message to standard error and exits; otherwise, a pointer is returned to
-\fBstdscr\fR.
-
-A program that outputs to more than one terminal should use the \fBnewterm\fR
-routine for each terminal instead of \fBinitscr\fR. A program that needs to
-inspect capabilities, so it can continue to run in a line-oriented mode if the
+.SS initscr
+\fBinitscr\fP is normally the first \fBcurses\fP routine to call when
+initializing a program.
+A few special routines sometimes need to be called before it;
+these are \fBslk_init\fP(3X), \fBfilter\fP, \fBripoffline\fP,
+\fBuse_env\fP.
+For multiple-terminal applications,
+\fBnewterm\fP may be called before \fBinitscr\fP.
+.PP
+The initscr code determines the terminal type and initializes all \fBcurses\fP
+data structures.
+\fBinitscr\fP also causes the first call to \fBrefresh\fP(3X)
+to clear the screen.
+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\fR. The routine \fBnewterm\fR should be called once for each
-terminal. It returns a variable of type \fBSCREEN *\fR which should be saved
-as a reference to that terminal. The arguments are the \fItype\fR of the
-terminal to be used in place of \fB$TERM\fR, a file pointer for output to the
-terminal, and another file pointer for input from the terminal (if \fItype\fR
-is \fBNULL\fR, \fB$TERM\fR will be used). The program must also call
-\fBendwin\fR for each terminal being used before exiting from \fBcurses\fR.
-If \fBnewterm\fR is called more than once for the same terminal, the first
-terminal referred to must be the last one for which \fBendwin\fR is called.
-
-A program should always call \fBendwin\fR before exiting or escaping from
-\fBcurses\fR mode temporarily. This routine restores tty modes, moves the
-cursor to the lower left-hand corner of the screen and resets the terminal into
-the proper non-visual mode. Calling \fBrefresh\fR or \fBdoupdate\fR after a
+\fBnewterm\fP.
+The routine \fBnewterm\fP should be called once for each terminal.
+It returns a variable of type \fBSCREEN *\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
+.bP
+another file pointer for input from the terminal
+.PP
+If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used.
+.SS endwin
+.PP
+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
+terminal referred to must be the last one for which \fBendwin\fP is called.
+.PP
+A program should always call \fBendwin\fP before exiting or escaping from
+\fBcurses\fP mode temporarily.
+This routine
+.bP
+resets colors to correspond with the default color pair 0,
+.bP
+moves the cursor to the lower left-hand corner of the screen,
+.bP
+clears the remainder of the line so that it uses the default colors,
+.bP
+sets the cursor to normal visibility (see \fBcurs_set\fP(3X)),
+.bP
+stops cursor-addressing mode using the \fIexit_ca_mode\fP terminal capability,
+.bP
+restores tty modes (see \fBreset_shell_mode\fP(3X)).
+.PP
+Calling \fBrefresh\fP(3X) or \fBdoupdate\fP(3X) after a
temporary escape causes the program to resume visual mode.
-
-The \fBisendwin\fR routine returns \fBTRUE\fR if \fBendwin\fR has been
-called without any subsequent calls to \fBwrefresh\fR, and \fBFALSE\fR
-otherwise.
-
-The \fBset_term\fR routine is used to switch between different
-terminals. The screen reference \fBnew\fR becomes the new current
-terminal. The previous terminal is returned by the routine. This is
-the only routine which manipulates \fBSCREEN\fR pointers; all other
-routines affect only the current terminal.
-
-The \fBdelscreen\fR routine frees storage associated with the
-\fBSCREEN\fR data structure. The \fBendwin\fR routine does not do
-this, so \fBdelscreen\fR should be called after \fBendwin\fR if a
-particular \fBSCREEN\fR is no longer needed.
+.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;
+all other routines affect only the current terminal.
+.SS delscreen
+.PP
+The \fBdelscreen\fP routine frees storage associated with the
+\fBSCREEN\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.
.SH RETURN VALUE
-\fBendwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
+\fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP
upon successful completion.
-
-Routines that return pointers always return \fBNULL\fR on error.
-.SH NOTES
-Note that \fBinitscr\fR and \fBnewterm\fR may be macros.
+.PP
+Routines that return pointers always return \fBNULL\fP on error.
+.PP
+X/Open defines no error conditions.
+In this implementation
+.bP
+\fBendwin\fP returns an error if the terminal was not initialized.
+.bP
+\fBnewterm\fP
+returns an error 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.
+.bP
+\fBset_term\fP
+returns no error.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4. It
-specifies that portable applications must not call \fBinitscr\fR more than
-once.
+These functions were described in the XSI Curses standard, Issue 4.
+As of 2015, the current document is X/Open Curses, Issue 7.
+.SS Differences
+X/Open 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))
+to restore the screen after \fBendwin\fP.
+.bP
+This implementation allows using \fBinitscr\fP after \fBendwin\fP.
+.PP
+Old versions of curses, e.g., BSD 4.4, may have returned 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.
+.SS Unset TERM Variable
+.PP
+If the TERM 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:
+.RS 5
+.PP
+\fICurses implementations may provide for special handling of the \fBSIGINT\fP,
+\fBSIGQUIT\fP and \fBSIGTSTP\fP signals
+if their disposition is \fBSIG_DFL\fP at the time
+\fBinitscr\fP is called \fP...
+.PP
+\fIAny 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.\fP
+.PP
+\fINone of the Curses functions are required to be safe
+with respect to signals \fP...
+.RE
+.PP
+This implementation establishes signal handlers during initialization,
+e.g., \fBinitscr\fP or \fBnewterm\fP.
+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.
+Although it \fIusually\fP works as expected, there are limitations:
+.RS 5
+.bP
+Walking the \fBSCREEN\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.
+.RE
+.TP 5
+.B SIGTERM
+This uses the same handler as \fBSIGINT\fP, with the same limitations.
+It is not mentioned in X/Open Curses, but is more suitable for this
+purpose than \fBSIGQUIT\fP (which is used in debugging).
+.TP 5
+.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
+assuming that it has been completely altered.
+It also updates the saved terminal modes with \fBdef_shell_mode\fP
+(see \fBcurs_kernel\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)).
+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\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_refresh\fR(3X),
-\fBcurs_slk\fR(3X), \fBcurs_util\fR(3X)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\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).
projects / ncurses.git / blobdiff