+ The routine <STRONG>newterm</STRONG> should be called once for each terminal. It re-
+ turns a variable of type <STRONG>SCREEN</STRONG> <STRONG>*</STRONG> which should be saved as a reference
+ to that terminal. <STRONG>newterm</STRONG>'s arguments are
+
+ <STRONG>o</STRONG> the <EM>type</EM> of the terminal to be used in place of <STRONG>$TERM</STRONG>,
+
+ <STRONG>o</STRONG> an output stream connected to the terminal, and
+
+ <STRONG>o</STRONG> an input stream connected to the terminal
+
+ If the <EM>type</EM> parameter is <STRONG>NULL</STRONG>, <STRONG>$TERM</STRONG> will be used.
+
+ The file descriptor of the output stream is passed to <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>,
+ which returns a pointer to a <STRONG>TERMINAL</STRONG> structure. <STRONG>newterm</STRONG>'s return val-
+ ue holds a pointer to the <STRONG>TERMINAL</STRONG> structure.
+
+
+</PRE><H3><a name="h3-endwin">endwin</a></H3><PRE>
+ The program must also call <STRONG>endwin</STRONG> for each terminal being used before
+ exiting from <STRONG>curses</STRONG>. If <STRONG>newterm</STRONG> is called more than once for the same
+ terminal, the first terminal referred to must be the last one for which
+ <STRONG>endwin</STRONG> is called.
+
+ A program should always call <STRONG>endwin</STRONG> before exiting or escaping from
+ <STRONG>curses</STRONG> mode temporarily. This routine
+
+ <STRONG>o</STRONG> resets colors to correspond with the default color pair 0,
+
+ <STRONG>o</STRONG> moves the cursor to the lower left-hand corner of the screen,
+
+ <STRONG>o</STRONG> clears the remainder of the line so that it uses the default col-
+ ors,
+
+ <STRONG>o</STRONG> sets the cursor to normal visibility (see <STRONG><A HREF="curs_kernel.3x.html">curs_set(3x)</A></STRONG>),
+
+ <STRONG>o</STRONG> stops cursor-addressing mode using the <EM>exit</EM><STRONG>_</STRONG><EM>ca</EM><STRONG>_</STRONG><EM>mode</EM> terminal capa-
+ bility,
+
+ <STRONG>o</STRONG> restores tty modes (see <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG>).
+
+ Calling <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> after a temporary escape causes the
+ program to resume visual mode.
+
+
+</PRE><H3><a name="h3-isendwin">isendwin</a></H3><PRE>
+ The <STRONG>isendwin</STRONG> routine returns <STRONG>TRUE</STRONG> if <STRONG>endwin</STRONG> has been called without any
+ subsequent calls to <STRONG>wrefresh</STRONG>, and <STRONG>FALSE</STRONG> otherwise.
+
+
+</PRE><H3><a name="h3-set_term">set_term</a></H3><PRE>
+ The <STRONG>set_term</STRONG> routine is used to switch between different terminals.
+ The screen reference <EM>new</EM> becomes the new current terminal. The previ-
+ ous terminal is returned by the routine. This is the only routine
+ which manipulates <STRONG>SCREEN</STRONG> pointers; all other routines affect only the
+ current terminal.
+
+
+</PRE><H3><a name="h3-delscreen">delscreen</a></H3><PRE>
+ The <STRONG>delscreen</STRONG> routine frees storage associated with the <STRONG>SCREEN</STRONG> data
+ structure. The <STRONG>endwin</STRONG> routine does not do this, so <STRONG>delscreen</STRONG> should be
+ called after <STRONG>endwin</STRONG> if a particular <STRONG>SCREEN</STRONG> is no longer needed.
+
+
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+ <STRONG>endwin</STRONG> returns the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon successful com-
+ pletion.
+
+ Routines that return pointers always return <STRONG>NULL</STRONG> on error.
+
+ X/Open defines no error conditions. In this implementation
+
+ <STRONG>o</STRONG> <STRONG>endwin</STRONG> returns an error if the terminal was not initialized.
+
+ <STRONG>o</STRONG> <STRONG>newterm</STRONG> returns an error if it cannot allocate the data structures
+ for the screen, or for the top-level windows within the screen,
+ i.e., <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, or <STRONG>stdscr</STRONG>.
+
+ <STRONG>o</STRONG> <STRONG>set_term</STRONG> returns no error.
+
+
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ These functions were described in the XSI Curses standard, Issue 4. As
+ of 2015, the current document is X/Open Curses, Issue 7.
+
+
+</PRE><H3><a name="h3-Differences">Differences</a></H3><PRE>
+ X/Open specifies that portable applications must not call <STRONG>initscr</STRONG> more
+ than once:
+
+ <STRONG>o</STRONG> The portable way to use <STRONG>initscr</STRONG> is once only, using <STRONG>refresh</STRONG> (see
+ <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>) to restore the screen after <STRONG>endwin</STRONG>.
+
+ <STRONG>o</STRONG> This implementation allows using <STRONG>initscr</STRONG> after <STRONG>endwin</STRONG>.
+
+ Old versions of curses, e.g., BSD 4.4, would return a null pointer from
+ <STRONG>initscr</STRONG> when an error is detected, rather than exiting. It is safe but
+ redundant to check the return value of <STRONG>initscr</STRONG> in XSI Curses.
+
+ Calling <STRONG>endwin</STRONG> does not dispose of the memory allocated in <STRONG>initscr</STRONG> or
+ <STRONG>newterm</STRONG>. Deleting a <STRONG>SCREEN</STRONG> provides a way to do this:
+
+ <STRONG>o</STRONG> X/Open Curses does not say what happens to <STRONG>WINDOW</STRONG>s when <STRONG>delscreen</STRONG>
+ "frees storage associated with the <STRONG>SCREEN</STRONG>" nor does the SVr4 docu-
+ mentation help, adding that it should be called after <STRONG>endwin</STRONG> if a
+ <STRONG>SCREEN</STRONG> is no longer needed.
+
+ <STRONG>o</STRONG> However, <STRONG>WINDOW</STRONG>s are implicitly associated with a <STRONG>SCREEN</STRONG>. so that
+ it is reasonable to expect <STRONG>delscreen</STRONG> to deal with these.
+
+ <STRONG>o</STRONG> SVr4 curses deletes the standard <STRONG>WINDOW</STRONG> structures <STRONG>stdscr</STRONG> and
+ <STRONG>curscr</STRONG> as well as a work area <STRONG>newscr</STRONG>. SVr4 curses ignores other
+ windows.
+
+ <STRONG>o</STRONG> Since version 4.0 (1996), ncurses has maintained a list of all win-
+ dows for each screen, using that information to delete those win-
+ dows when <STRONG>delscreen</STRONG> is called.
+
+ <STRONG>o</STRONG> NetBSD copied this feature of ncurses in 2001. PDCurses follows
+ the SVr4 model, deleting only the standard <STRONG>WINDOW</STRONG> structures.
+
+
+</PRE><H3><a name="h3-High-level-versus-low-level">High-level versus low-level</a></H3><PRE>
+ Different implementations may disagree regarding the level of some
+ functions. For example, <STRONG>SCREEN</STRONG> (returned by <STRONG>newterm</STRONG>) and <STRONG>TERMINAL</STRONG> (re-
+ turned by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>) hold file descriptors for the output stream.
+ If an application switches screens using <STRONG>set_term</STRONG>, or switches termi-
+ nals using <STRONG><A HREF="curs_terminfo.3x.html">set_curterm(3x)</A></STRONG>, applications which use the output file de-
+ scriptor can have different behavior depending on which structure holds
+ the corresponding descriptor.
+
+ For example
+
+ <STRONG>o</STRONG> NetBSD's <STRONG><A HREF="curs_termattrs.3x.html">baudrate(3x)</A></STRONG> function uses the descriptor in <STRONG>TERMINAL</STRONG>.
+ <STRONG>ncurses</STRONG> and SVr4 use the descriptor in <STRONG>SCREEN</STRONG>.
+
+ <STRONG>o</STRONG> NetBSD and <STRONG>ncurses</STRONG> use the descriptor in <STRONG>TERMINAL</STRONG> for terminal I/O
+ modes, e.g., <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">def_prog_mode(3x)</A></STRONG>. SVr4 curses
+ uses the descriptor in <STRONG>SCREEN</STRONG>.
+
+
+</PRE><H3><a name="h3-Unset-TERM-Variable">Unset TERM Variable</a></H3><PRE>
+ If the TERM variable is missing or empty, <STRONG>initscr</STRONG> uses the value "un-
+ known", which normally corresponds to a terminal entry with the <EM>generic</EM>
+ (<EM>gn</EM>) capability. Generic entries are detected by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> and
+ cannot be used for full-screen operation. Other implementations may
+ handle a missing/empty TERM variable differently.
+
+
+</PRE><H3><a name="h3-Signal-Handlers">Signal Handlers</a></H3><PRE>
+ Quoting from X/Open Curses, section 3.1.1: