@@ -72,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.
@@ -86,9 +86,9 @@
if the terminal cannot support a screen-oriented program, would also
use newterm.
- The routine newterm should be called once for each terminal. It re-
- turns a variable of type SCREEN* which should be saved as a reference
- to that terminal. newterm's arguments are
+ 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,
@@ -99,8 +99,8 @@
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 val-
- ue holds a pointer to the TERMINAL structure.
+ which returns a pointer to a TERMINAL structure. newterm's return
+ value holds a pointer to the TERMINAL structure.
@@ -116,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)).
@@ -137,134 +137,139 @@
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 ERR if
- onewterm returns an error if it cannot allocate the data structures
- for the screen, or for the top-level windows within the screen,
- i.e., curscr, newscr, or stdscr.
+ o the terminal was not initialized, or
+
+ oendwin is called more than once without updating the screen, or
+
+ oreset_shell_mode(3x) return ERR.
+
+ onewterm returns ERR if it cannot allocate the data structures for
+ the screen, or for the top-level windows within the screen, i.e.,
+ curscr, newscr, or stdscr.
oset_term returns no error.
- 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, 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 XSI Curses.
+ 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:
+ 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 docu-
- mentation help, adding that it should be called after endwin if a
- SCREEN is no longer needed.
+ 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
+ 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
+ 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 win-
- dows for each screen, using that information to delete those win-
- dows when delscreen is called.
+ 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.
+ 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 (re-
- turned by setupterm(3x)) hold file descriptors for the output stream.
- If an application switches screens using set_term, or switches termi-
- nals using set_curterm(3x), applications which use the output file de-
- scriptor can have different behavior depending on which structure holds
- the corresponding descriptor.
+ 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'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
+ 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.
-
+ 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(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
- thelifeoftheprocessoruntiltheprocesschangesthe
- dispositionofthesignal.
+ 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,
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.
@@ -274,27 +279,31 @@
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)).
+ 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.
+ standardization efforts. The handler sets a (signal-safe)
+ variable that is later tested by wgetch(3x) and wget_wch(3x).
+
+ owgetch returns the key code KEY_RESIZE.
+
+ owget_wch returns KEY_CODE_YES and sets its wch parameter to
+ KEY_RESIZE.
+
+ At the same time, ncurses calls resizeterm to adjust the standard
+ screen stdscr, and update other data such as LINES and COLS.