X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_initscr.3x;h=3451991b239de6edf1b7ed92be7560a8bd086351;hb=b3719ca8b52aa07d0d85f7c1ce645a471397ccfe;hp=17e5fb9c5adcd4c39bb45df617e54fd660a5628f;hpb=16fbf3f4f7d96b6ee6bf9159b22f26e05962aa3d;p=ncurses.git

diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x
index 17e5fb9c..3451991b 100644
--- a/man/curs_initscr.3x
+++ b/man/curs_initscr.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
+.\" Copyright 2018-2022,2023 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.37 2022/02/12 20:07:29 tom Exp $
+.\" $Id: curs_initscr.3x,v 1.40 2023/06/10 16:50:22 tom Exp $
 .TH curs_initscr 3X ""
 .de bP
 .ie n  .IP \(bu 4
@@ -57,7 +57,7 @@
 .sp
 \fBbool isendwin(void);\fP
 .sp
-\fBSCREEN *newterm(const char *\fItype\fB, FILE *\fIoutfd\fB, FILE *\fIinfd\fB);\fR
+\fBSCREEN *newterm(const char *\fItype\fB, FILE *\fIoutf\fB, FILE *\fIinf\fB);\fR
 .br
 \fBSCREEN *set_term(SCREEN *\fInew\fB);\fR
 .br
@@ -88,6 +88,7 @@ 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
 as a reference to that terminal.
@@ -95,11 +96,15 @@ as a reference to that terminal.
 .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.
+.PP
+The file descriptor of the output stream is passed to \fBsetupterm\fP(3X),
+which returns a pointer to a \fBTERMINAL\fP structure.
+\fBnewterm\fP's return value holds a pointer to the \fBTERMINAL\fP structure.
 .SS endwin
 .PP
 The program must also call
@@ -176,18 +181,63 @@ 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 High-level versus low-level
+Different implementations may disagree regarding the level of some functions.
+For example, \fBSCREEN\fP (returned by \fBnewterm\fP) and
+\fBTERMINAL\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
+For example
+.bP
+NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fBTERMINAL\fP.
+\fBncurses\fP and SVr4 use the descriptor in \fBSCREEN\fP.
+.bP
+NetBSD and \fBncurses\fP use the descriptor in \fBTERMINAL\fP for terminal I/O modes,
+e.g.,
+\fBdef_shell_mode\fP(3X),
+\fBdef_prog_mode\fP(3X).
+SVr4 curses uses the descriptor in \fBSCREEN\fP.
 .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.
+Generic entries are detected by \fBsetupterm\fP(3X)
+and cannot be used for full-screen operation.
 Other implementations may handle a missing/empty TERM variable differently.
 .SS Signal Handlers
 .PP