- initscr is normally the first curses routine to call when
- initializing a program. A few special routines sometimes
- need to be called before it; these are slk_init, filter,
- ripoffline, use_env. For multiple-terminal applications,
- newterm may be called before initscr.
+ initscr is normally the first curses routine to call when initializing
+ a program. A few special routines sometimes need to be called before
+ 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 initial-
- izes all curses data structures. initscr also causes the
- first call to refresh to clear the screen. If errors oc-
- cur, initscr writes an appropriate error message to stan-
- dard error and exits; otherwise, a pointer is returned 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.
- A program that outputs to more than one terminal should
- use the newterm 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 ter-
- minal cannot support a screen-oriented program, would also
- 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
+ A program that outputs to more than one terminal should use the newterm
+ 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 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 exiting from curses. If newterm is called
- more than once for the same terminal, the first terminal
- referred to must be the last one for which endwin is
- called.
+ The program must also call endwin for each terminal being used before
+ exiting from curses. If newterm is called more than once for the same
+ terminal, the first terminal referred to must be the last one for which
+ endwin is called.
+
+ A program should always call endwin before exiting or escaping from
+ curses mode temporarily. This routine
- A program should always call endwin before exiting or es-
- caping from curses mode temporarily. This routine
+ o resets colors to correspond with the default color pair 0,
- o restores tty modes,
+ o moves the cursor to the lower left-hand corner of the screen,
- o moves the cursor to the lower left-hand corner of the
- screen and
+ o clears the remainder of the line so that it uses the default
+ colors,
- o resets the terminal into the proper non-visual mode.
+ o sets the cursor to normal visibility (see curs_set(3x)),
- Calling refresh or doupdate after a temporary escape caus-
- es the program to resume visual mode.
+ o stops cursor-addressing mode using the exit_ca_mode terminal
+ capability,
+
+ o restores tty modes (see reset_shell_mode(3x)).
+
+ Calling refresh(3x) or doupdate(3x) after a temporary escape causes the
+ program to resume visual mode.
- The isendwin routine returns TRUE if endwin has been
- called without any subsequent calls to wrefresh, and FALSE
- otherwise.
+ The isendwin routine returns TRUE if endwin has been called without any
+ subsequent calls to wrefresh, and FALSE otherwise.
- The set_term routine is used to switch between different
- terminals. The screen reference new becomes the new cur-
- rent terminal. The previous terminal is returned by the
- routine. This is the only routine which manipulates
- SCREEN pointers; all other routines affect only the cur-
- rent terminal.
+ The set_term routine is used to switch between different terminals.
+ 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 structure. The endwin routine does not do
- this, so delscreen should be called after endwin if a par-
- ticular SCREEN is no longer needed.
+ 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.
- endwin returns the integer ERR upon failure and OK upon
- successful completion.
+ 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 implementa-
- tion
+ X/Open defines no error conditions. In this implementation
- oendwin returns an error if the terminal was not ini-
- tialized.
+ oendwin returns an error if
- onewterm returns an error if it cannot allocate the da-
- ta 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
- oset_term returns no error.
+ oendwin is called more than once without updating the screen, or
+ oreset_shell_mode(3x) returns an error.
-
- Note that initscr and newterm may be macros.
+ 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.
+
+ 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 Curs-
- es, 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
+ 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 "unknown", which normally corresponds to a terminal
- entry with the generic (gn) capability. Generic entries
- are detected by setupterm (see curs_terminfo(3x)) and can-
- not be used for full-screen operation. Other implementa-
- tions may handle a missing/empty TERM variable different-
- ly.
+ 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:
- Cursesimplementationsmayprovideforspecialhan-
- dlingoftheSIGINT,SIGQUITandSIGTSTPsignalsif
- theirdispositionisSIG_DFLatthetimeinitscr()is
- called...
+ 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...
- Anyspecialhandlingforthesesignalsmayremainin
- effectforthelifeoftheprocessoruntilthe
- processchangesthedispositionofthesignal.
+ 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.
- NoneoftheCursesfunctionsarerequiredtobesafe
- withrespecttosignals ...
+ 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 corre-
- sponding handlers after initializing the library:
+ 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
+ library:
SIGINT
- The handler attempts to cleanup the screen on exit.
- Although it usually works as expected, there are lim-
- itations:
+ 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 is done without any signal blocking.
+ 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 functions 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 clear-
- ly 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 purpose than SIGQUIT
- (which is used in debugging).
+ 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 dis-
- cards 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 ini-
- tially ignored in the standardization efforts. The
- handler sets a (signal-safe) variable 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.