.\"***************************************************************************
-.\" 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_initscr.3x,v 1.39 2022/07/24 15:46:49 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
.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
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.
.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
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