X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_initscr.3x;h=5e17ead0a659bd23838095397ea0e3b03bb0a443;hb=3183ac61c6bf0a75ee65dc8cbebf54f7c143df46;hp=00366177df527212366e55010d85fd11d9b014ca;hpb=74433bcf4f6fe40862a28f3c00edaedcd5054b01;p=ncurses.git

diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x
index 00366177..5e17ead0 100644
--- a/man/curs_initscr.3x
+++ b/man/curs_initscr.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_initscr.3x,v 1.36 2021/12/25 21:41:58 tom Exp $
+.\" $Id: curs_initscr.3x,v 1.39 2022/07/24 15:46:49 tom Exp $
 .TH curs_initscr 3X ""
 .de bP
 .ie n  .IP \(bu 4
@@ -57,11 +57,11 @@
 .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
+\fBSCREEN *newterm(const char *\fItype\fB, FILE *\fIoutfd\fB, FILE *\fIinfd\fB);\fR
 .br
-\fBSCREEN *set_term(SCREEN *\fP\fInew\fP\fB);\fP
+\fBSCREEN *set_term(SCREEN *\fInew\fB);\fR
 .br
-\fBvoid delscreen(SCREEN* \fP\fIsp\fP\fB);\fP
+\fBvoid delscreen(SCREEN* \fIsp\fB);\fR
 .br
 .SH DESCRIPTION
 .SS initscr
@@ -176,10 +176,35 @@ 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
+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.
+.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:
+.bP
+X/Open Curses does not say what happens to \fBWINDOW\fPs when \fBdelscreen\fP
+\*(``frees storage associated with the \fBSCREEN\fP\*(''
+nor does the SVr4 documentation help,
+adding that it should be called after \fBendwin\fP if a \fBSCREEN\fP
+is no longer needed.
+.bP
+However, \fBWINDOW\fPs are implicitly associated with a \fBSCREEN\fP.
+so that it is reasonable to expect \fBdelscreen\fP to deal with these.
+.bP
+SVr4 curses deletes the standard \fBWINDOW\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,
+using that information to delete those windows when \fBdelscreen\fP is called.
+.bP
+NetBSD copied this feature of ncurses in 2001.
+PDCurses follows the SVr4 model,
+deleting only the standard \fBWINDOW\fP structures.
 .SS Unset TERM Variable
 .PP
 If the TERM variable is missing or empty, \fBinitscr\fP uses the
@@ -193,19 +218,23 @@ Other implementations may handle a missing/empty TERM variable differently.
 .PP
 Quoting from X/Open Curses, section 3.1.1:
 .RS 5
+.hy 0
 .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...
+.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...
 .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
+.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.
 .PP
-\fINone of the Curses functions are required to be safe
-with respect to signals \fP...
+.I None of the Curses functions are required to be safe
+.I with respect to signals \fP...
 .RE
+.hy
 .PP
 This implementation establishes signal handlers during initialization,
 e.g., \fBinitscr\fP or \fBnewterm\fP.