ncurses 6.4 - patch 20230610

[ncurses.git] / man / curs_initscr.3x

diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x
index 5e17ead0a659bd23838095397ea0e3b03bb0a443..3451991b239de6edf1b7ed92be7560a8bd086351 100644 (file)
--- 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  *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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
 .TH curs_initscr 3X ""
 .de bP
 .ie n  .IP \(bu 4


@@ -57,7 +57,7 @@
 .sp
 \fBbool isendwin(void);\fP
 .sp
 .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
 .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.
 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.
 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
 .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
 .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
 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
 .SS endwin
 .PP
 The program must also call


@@ -205,14 +210,34 @@ using that information to delete those windows when \fBdelscreen\fP is called.
 NetBSD copied this feature of ncurses in 2001.
 PDCurses follows the SVr4 model,
 deleting only the standard \fBWINDOW\fP structures.
 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.
 .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
 Other implementations may handle a missing/empty TERM variable differently.
 .SS Signal Handlers
 .PP