Manual Pages  — curs_threads

 NCURSES_WINDOW_CB,  NCURSES_SCREEN_CB,  get_escdelay,  set_escdelay,  set_tabsize,  use_screen,  use_window - curses support for multi-threaded applications

SYNOPSIS DESCRIPTION Usage RETURN VALUE NOTES PORTABILITY SEE ALSO

#include <curses.h>

/* data types */
typedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
typedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);

int get_escdelay(void);
int set_escdelay(int ms);
int set_tabsize(int cols);

int use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);
int use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);

The  ncurses library can be configured to support multi-threaded applications in a rudimentary way. Such configuration produces a different set of libraries, named libncursest, for example, since doing so alters  ncurses's application binary interface (ABI).

Instead of modifying the programming interface (API) to make  ncurses functions expect an additional argument specifying a thread, the library adds functions, usable in any configuration, that hide the mutexes (mutual exclusion locks) needed to prevent concurrent access to variables shared by multiple threads of execution.

 ncurses threading support requires the use of functions to access members of the  WINDOW structure (see curs_opaque(3X)). It further makes functions of the common global variables  COLORS,  COLOR_PAIRS,  COLS,  ESCDELAY,  LINES,  TABSIZE,  curscr,  newscr, and  ttytype, maintaining them as as read-only values in the SCREEN structure.

Even this is not enough to make an application using curses thread-safe. We would expect a multi-threaded application to have threads updating separate windows (on the same device), and separate screens (on different devices). Further, applications expect a few of the global variables to be writable. The functions described here address these special situations.

The  ESCDELAY and  TABSIZE global variables are modified by some applications. To modify them in any configuration, use the  set_escdelay or  set_tabsize functions. Other global variables are not modifiable. get_escdelay retrieves  ESCDELAY's value.

The use_window and use_screen functions provide coarse-grained mutexes for their respective  WINDOW and SCREEN parameters; they call a user-supplied function, pass it a data parameter, and return the value from the user-supplied function to the application.

All  ncurses library functions assume that the locale is not altered during operation. In addition, they use data that is maintained within a hierarchy of scopes.

»	global data used in the low-level terminfo or termcap interfaces
»	terminal data associated with a call to set_curterm(3X)
	Terminal data are initialized when screens are created.
»	screen data associated with a call to newterm(3X) or initscr(3X)
»	window data associated with a call to newwin(3X) or subwin(3X)
	Windows are associated with screens. Pads are not necessarily associated with any particular screen.
	Most curses applications operate on one or more windows within a single screen.
»	reentrant data associated with pure functions that alter no shared variables

The following table lists the scope of each symbol in the  ncurses library when configured to support multi-threaded applications.

 get_escdelay returns the value of  ESCDELAY.  set_escdelay and  set_tabsize return ERR upon failure and OK upon successful completion.  use_screen and  use_window return the int returned by the user-supplied function they are called with.

 ncurses provides both a C function and a preprocessor macro for each function documented in this page.

These routines are specific to  ncurses. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on  ncurses extensions be conditioned using  NCURSES_VERSION.

 curses(3X),  curs_opaque(3X),  curs_variables(3X)