@@ -56,8 +56,10 @@
WINDOW*initscr(void);intendwin(void);
+
boolisendwin(void);
- SCREEN*newterm(constchar*type,FILE*outfd,FILE*infd);
+
+ SCREEN*newterm(constchar*type,FILE*outf,FILE*inf);SCREEN*set_term(SCREEN*new);voiddelscreen(SCREEN*sp);
@@ -70,11 +72,11 @@
it; these are slk_init(3x), filter, ripoffline, use_env. For multiple-
terminal applications, newterm may be called before initscr.
- The initscr code determines the terminal type and initializes all curs-
- es data structures. initscr also causes the first call to refresh(3x)
- to clear the screen. If errors occur, initscr writes an appropriate
- error message to standard error and exits; otherwise, a pointer is re-
- turned to stdscr.
+ The initscr code determines the terminal type and initializes all
+ curses data structures. initscr also causes the first call to
+ refresh(3x) to clear the screen. If errors occur, initscr writes an
+ appropriate error message to standard error and exits; otherwise, a
+ pointer is returned to stdscr.
@@ -82,18 +84,24 @@
routine for each terminal instead of initscr. 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 newterm. The routine newterm should be called once for each termi-
- nal. It returns a variable of type SCREEN* which should be saved as a
+ use newterm.
+
+ The routine newterm should be called once for each terminal. It
+ returns a variable of type SCREEN* which should be saved as a
reference to that terminal. newterm's arguments are
o the type of the terminal to be used in place of $TERM,
- o a file pointer for output to the terminal, and
+ o an output stream connected to the terminal, and
- o another file pointer for input from the terminal
+ o an input stream connected to the terminal
If the type parameter is NULL, $TERM will be used.
+ The file descriptor of the output stream is passed to setupterm(3x),
+ which returns a pointer to a TERMINAL structure. newterm's return
+ value holds a pointer to the TERMINAL structure.
+
The program must also call endwin for each terminal being used before
@@ -108,13 +116,13 @@
o moves the cursor to the lower left-hand corner of the screen,
- o clears the remainder of the line so that it uses the default col-
- ors,
+ o clears the remainder of the line so that it uses the default
+ colors,
o sets the cursor to normal visibility (see curs_set(3x)),
- o stops cursor-addressing mode using the exit_ca_mode terminal capa-
- bility,
+ o stops cursor-addressing mode using the exit_ca_mode terminal
+ capability,
o restores tty modes (see reset_shell_mode(3x)).
@@ -129,27 +137,33 @@
The set_term routine is used to switch between different terminals.
- The screen reference new becomes the new current terminal. The previ-
- ous terminal is returned by the routine. This is the only routine
- which manipulates SCREEN pointers; all other routines affect only the
+ The screen reference new becomes the new current terminal. The
+ previous terminal is returned by the routine. This is the only routine
+ which manipulates SCREEN pointers; all other routines affect only the
current terminal.
- The delscreen routine frees storage associated with the SCREEN data
+ The delscreen routine frees storage associated with the SCREEN data
structure. The endwin routine does not do this, so delscreen should be
- called after endwin if a particular SCREEN is no longer needed.
+ called after endwin if a particular SCREEN is no longer needed.
- endwin returns the integer ERR upon failure and OK upon successful com-
- pletion.
+ endwin returns the integer ERR upon failure and OK upon successful
+ completion.
Routines that return pointers always return NULL on error.
X/Open defines no error conditions. In this implementation
- oendwin returns an error if the terminal was not initialized.
+ oendwin returns an error if
+
+ o the terminal was not initialized, or
+
+ oendwin is called more than once without updating the screen, or
+
+ oreset_shell_mode(3x) returns an error.
onewterm returns an error if it cannot allocate the data structures
for the screen, or for the top-level windows within the screen,
@@ -159,93 +173,133 @@
- These functions were described in the XSI Curses standard, Issue 4. As
- of 2015, the current document is X/Open Curses, Issue 7.
+ These functions were described in X/Open Curses, Issue 4. As of 2015,
+ the current document is X/Open Curses, Issue 7.
- X/Open specifies that portable applications must not call initscr more
- than once:
+ X/Open Curses specifies that portable applications must not call
+ initscr more than once:
- o The portable way to use initscr is once only, using refresh (see
- curs_refresh(3x)) to restore the screen after endwin.
+ o The portable way to use initscr is once only, using refresh(3x) to
+ restore the screen after endwin.
o This implementation allows using initscr after endwin.
- Old versions of curses, e.g., BSD 4.4, may have returned a null pointer
- from initscr when an error is detected, rather than exiting. It is
- safe but redundant to check the return value of initscr in XSI Curses.
+ Old versions of curses, e.g., BSD 4.4, would return a null pointer from
+ initscr when an error is detected, rather than exiting. It is safe but
+ redundant to check the return value of initscr in X/Open Curses.
+
+ Calling endwin does not dispose of the memory allocated in initscr or
+ newterm. Deleting a SCREEN provides a way to do this:
+
+ o X/Open Curses does not say what happens to WINDOWs when delscreen
+ "frees storage associated with the SCREEN" nor does the SVr4
+ documentation help, adding that it should be called after endwin if
+ a SCREEN is no longer needed.
+
+ o However, WINDOWs are implicitly associated with a SCREEN. so that
+ it is reasonable to expect delscreen to deal with these.
+
+ o SVr4 curses deletes the standard WINDOW structures stdscr and
+ curscr as well as a work area newscr. SVr4 curses ignores other
+ windows.
+
+ o Since version 4.0 (1996), ncurses has maintained a list of all
+ windows for each screen, using that information to delete those
+ windows when delscreen is called.
+
+ o NetBSD copied this feature of ncurses in 2001. PDCurses follows
+ the SVr4 model, deleting only the standard WINDOW structures.
+
+
+
+ Different implementations may disagree regarding the level of some
+ functions. For example, SCREEN (returned by newterm) and TERMINAL
+ (returned by setupterm(3x)) hold file descriptors for the output
+ stream. If an application switches screens using set_term, or switches
+ terminals using set_curterm(3x), applications which use the output file
+ descriptor can have different behavior depending on which structure
+ holds the corresponding descriptor.
+
+ For example
+
+ o NetBSD's baudrate(3x) function uses the descriptor in TERMINAL.
+ ncurses and SVr4 use the descriptor in SCREEN.
+ o NetBSD and ncurses use the descriptor in TERMINAL for terminal I/O
+ modes, e.g., def_shell_mode(3x), def_prog_mode(3x). SVr4 curses
+ uses the descriptor in SCREEN.
-
- If the TERM variable is missing or empty, initscr uses the value "un-
- known", which normally corresponds to a terminal entry with the generic
- (gn) capability. Generic entries are detected by setupterm (see
- curs_terminfo(3x)) and cannot be used for full-screen operation. Other
- implementations may handle a missing/empty TERM variable differently.
+ UnsetTERMVariable
+ If the TERM variable is missing or empty, initscr uses the value
+ "unknown", which normally corresponds to a terminal entry with the
+ generic (gn) capability. Generic entries are detected by setupterm(3x)
+ and cannot be used for full-screen operation. Other implementations
+ may handle a missing/empty TERM variable differently.
- Quoting from X/Open Curses, section 3.1.1:
+ Quoting from X/Open Curses Issue 7, section 3.1.1:
- Cursesimplementationsmayprovideforspecialhandlingofthe
- SIGINT,SIGQUITandSIGTSTPsignalsiftheirdispositionis
- SIG_DFLatthetimeinitscriscalled...
+ Curses implementations may provide for special handling of the
+ SIGINT, SIGQUIT, and SIGTSTP signals if their disposition is
+ SIG_DFL at the time initscr is called...
- Anyspecialhandlingforthesesignalsmayremainineffectfor
- thelifeoftheprocessoruntiltheprocesschangesthedisposi-
- tionofthesignal.
+ Any 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.
- NoneoftheCursesfunctionsarerequiredtobesafewithrespect
- tosignals ...
+ None of the Curses functions are required to be safe with respect
+ to signals...
- This implementation establishes signal handlers during initialization,
+ This implementation establishes signal handlers during initialization,
e.g., initscr or newterm. Applications which must handle these signals
- should set up the corresponding handlers after initializing the li-
- brary:
+ should set up the corresponding handlers after initializing the
+ library:
SIGINT
- The handler attempts to cleanup the screen on exit. Although it
+ The handler attempts to clean up the screen on exit. Although it
usually works as expected, there are limitations:
- o Walking the SCREEN list is unsafe, since all list management
+ o Walking the SCREEN list is unsafe, since all list management
is done without any signal blocking.
- o On systems which have REENTRANT turned on, set_term uses func-
- tions which could deadlock or misbehave in other ways.
+ o On systems which have REENTRANT turned on, set_term uses
+ functions which could deadlock or misbehave in other ways.
- oendwin calls other functions, many of which use stdio or other
- library functions which are clearly unsafe.
+ oendwin calls other functions, many of which use stdio(3) or
+ other library functions which are clearly unsafe.
SIGTERM
- This uses the same handler as SIGINT, with the same limitations.
- It is not mentioned in X/Open Curses, but is more suitable for
+ This uses the same handler as SIGINT, with the same limitations.
+ It is not mentioned in X/Open Curses, but is more suitable for
this purpose than SIGQUIT (which is used in debugging).
SIGTSTP
- This handles the stop signal, used in job control. When resuming
- the process, this implementation discards pending input with
- flushinput (see curs_util(3x)), and repaints the screen assuming
- that it has been completely altered. It also updates the saved
- terminal modes with def_shell_mode (see curs_kernel(3x)).
+ This handles the stop signal, used in job control. When resuming
+ the process, this implementation discards pending input with
+ flushinp(3x), and repaints the screen assuming that it has been
+ completely altered. It also updates the saved terminal modes with
+ def_shell_mode(3x).
SIGWINCH
- This handles the window-size changes which were ignored in the
- standardization efforts. The handler sets a (signal-safe) vari-
- able which is later tested in wgetch (see curs_getch(3x)). If
- keypad has been enabled for the corresponding window, wgetch re-
- turns the key symbol KEY_RESIZE. At the same time, wgetch calls
- resizeterm to adjust the standard screen stdscr, and update other
- data such as LINES and COLS.
+ This handles the window-size changes which were ignored in the
+ standardization efforts. The handler sets a (signal-safe)
+ variable which is later tested in wgetch(3x). If keypad has been
+ enabled for the corresponding window, wgetch returns the key
+ symbol KEY_RESIZE. At the same time, wgetch calls resizeterm to
+ adjust the standard screen stdscr, and update other data such as
+ LINES and COLS.