NAME

curs_threads - curses thread support

SYNOPSIS

#include <curses.h>

typedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
typedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);
int get_escdelay(void);
int set_escdelay(int size);
int set_tabsize(int size);
int use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);
int use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);

DESCRIPTION

This implementation can be configured to provide rudimentary support for multi-threaded applications. This makes a different set of libraries, e.g., libncursest since the binary interfaces are different.

Rather than modify the interfaces to pass a thread specifier to each function, it adds a few functions which can be used in any configuration which hide the mutex's needed to prevent concurrent use of the global variables when configured for threading.

In addition to forcing access to members of the WINDOW structure to be via functions (see curs_opaque(3X)), it makes functions of the common global variables, e.g., COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE curscr, newscr and ttytype. Those variables are maintained as read-only values, stored in the SCREEN structure.

Even this is not enough to make a thread-safe application using curses. A multi-threaded application would be expected to have threads updating separate windows (within the same device), or updating on separate screens (on different devices). Also, a few of the global variables are considered writable by some applications. 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.

The get_escdelay function returns the value for ESCDELAY.

The use_window and use_screen functions provide coarse granularity mutexes for their respective WINDOW and SCREEN parameters, and call a user-supplied function, passing it a data parameter, and returning the value from the user-supplied function to the application.

USAGE

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

global data, e.g., used in the low-level terminfo or termcap interfaces.
terminal data, e.g., associated with a call to set_curterm. The terminal data are initialized when screens are created.
screen data, e.g., associated with a call to newterm or initscr.
window data, e.g., associated with a call to newwin or subwin. Windows are associated with screens. Pads are not necessarily associated with a particular screen.

: Most curses applications operate on one or more windows within a single screen.

•: reentrant, i.e., it uses only the data passed as parameters.

This table lists the scope of data used for each symbol in the ncurses library when it is configured to support threading:

Symbol	Scope
BC	global
COLORS	screen (readonly)
COLOR_PAIR	reentrant
COLOR_PAIRS	screen (readonly)
COLS	screen (readonly)
ESCDELAY	screen (readonly, see set_escdelay)
LINES	screen (readonly)
PAIR_NUMBER	reentrant
PC	global
SP	global
TABSIZE	screen (readonly)
UP	global
acs_map	screen (readonly)
add_wch	window (stdscr)
add_wchnstr	window (stdscr)
add_wchstr	window (stdscr)
addch	window (stdscr)
addchnstr	window (stdscr)
addchstr	window (stdscr)
addnstr	window (stdscr)
addnwstr	window (stdscr)
addstr	window (stdscr)
addwstr	window (stdscr)
assume_default_colors	screen
attr_get	window (stdscr)
attr_off	window (stdscr)
attr_on	window (stdscr)
attr_set	window (stdscr)
attroff	window (stdscr)
attron	window (stdscr)
attrset	window (stdscr)
baudrate	screen
beep	screen
bkgd	window (stdscr)
bkgdset	window (stdscr)
bkgrnd	window (stdscr)
bkgrndset	window (stdscr)
boolcodes	global (readonly)
boolfnames	global (readonly)
boolnames	global (readonly)
border	window (stdscr)
border_set	window (stdscr)
box	window (stdscr)
box_set	window (stdscr)
can_change_color	terminal
cbreak	screen
chgat	window (stdscr)
clear	window (stdscr)
clearok	window
clrtobot	window (stdscr)
clrtoeol	window (stdscr)
color_content	screen
color_set	window (stdscr)
copywin	window locks(source, target)
cur_term	terminal
curs_set	screen
curscr	screen (readonly)
curses_version	global (readonly)
def_prog_mode	terminal
def_shell_mode	terminal
define_key	screen
del_curterm	screen
delay_output	screen
delch	window (stdscr)
deleteln	window (stdscr)
delscreen	global locks(screenlist, screen)
delwin	global locks(windowlist)
derwin	screen
doupdate	screen
dupwin	screen locks(window)
echo	screen
echo_wchar	window (stdscr)
echochar	window (stdscr)
endwin	screen
erase	window (stdscr)
erasechar	window (stdscr)
erasewchar	window (stdscr)
filter	global
flash	terminal
flushinp	screen
get_wch	screen (input-operation)
get_wstr	screen (input-operation)
getattrs	window
getbegx	window
getbegy	window
getbkgd	window
getbkgrnd	window
getcchar	reentrant
getch	screen (input-operation)
getcurx	window
getcury	window
getmaxx	window
getmaxy	window
getmouse	screen (input-operation)
getn_wstr	screen (input-operation)
getnstr	screen (input-operation)
getparx	window
getpary	window
getstr	screen (input-operation)
getwin	screen (input-operation)
halfdelay	screen
has_colors	terminal
has_ic	terminal
has_il	terminal
has_key	screen
hline	window (stdscr)
hline_set	window (stdscr)
idcok	window
idlok	window
immedok	window
in_wch	window (stdscr)
in_wchnstr	window (stdscr)
in_wchstr	window (stdscr)
inch	window (stdscr)
inchnstr	window (stdscr)
inchstr	window (stdscr)
init_color	screen
init_pair	screen
initscr	global locks(screenlist)
innstr	window (stdscr)
innwstr	window (stdscr)
ins_nwstr	window (stdscr)
ins_wch	window (stdscr)
ins_wstr	window (stdscr)
insch	window (stdscr)
insdelln	window (stdscr)
insertln	window (stdscr)
insnstr	window (stdscr)
insstr	window (stdscr)
instr	window (stdscr)
intrflush	terminal
inwstr	window (stdscr)
is_cleared	window
is_idcok	window
is_idlok	window
is_immedok	window
is_keypad	window
is_leaveok	window
is_linetouched	window
is_nodelay	window
is_notimeout	window
is_scrollok	window
is_syncok	window
is_term_resized	terminal
is_wintouched	window
isendwin	screen
key_defined	screen
key_name	global (static data)
keybound	screen
keyname	global (static data)
keyok	screen
keypad	window
killchar	terminal
killwchar	terminal
leaveok	window
longname	screen
mcprint	terminal
meta	screen
mouse_trafo	window (stdscr)
mouseinterval	screen
mousemask	screen
move	window (stdscr)
mvadd_wch	window (stdscr)
mvadd_wchnstr	window (stdscr)
mvadd_wchstr	window (stdscr)
mvaddch	window (stdscr)
mvaddchnstr	window (stdscr)
mvaddchstr	window (stdscr)
mvaddnstr	window (stdscr)
mvaddnwstr	window (stdscr)
mvaddstr	window (stdscr)
mvaddwstr	window (stdscr)
mvchgat	window (stdscr)
mvcur	screen
mvdelch	window (stdscr)
mvderwin	window (stdscr)
mvget_wch	screen (input-operation)
mvget_wstr	screen (input-operation)
mvgetch	screen (input-operation)
mvgetn_wstr	screen (input-operation)
mvgetnstr	screen (input-operation)
mvgetstr	screen (input-operation)
mvhline	window (stdscr)
mvhline_set	window (stdscr)
mvin_wch	window (stdscr)
mvin_wchnstr	window (stdscr)
mvin_wchstr	window (stdscr)
mvinch	window (stdscr)
mvinchnstr	window (stdscr)
mvinchstr	window (stdscr)
mvinnstr	window (stdscr)
mvinnwstr	window (stdscr)
mvins_nwstr	window (stdscr)
mvins_wch	window (stdscr)
mvins_wstr	window (stdscr)
mvinsch	window (stdscr)
mvinsnstr	window (stdscr)
mvinsstr	window (stdscr)
mvinstr	window (stdscr)
mvinwstr	window (stdscr)
mvprintw	window (stdscr)
mvscanw	screen
mvvline	window (stdscr)
mvvline_set	window (stdscr)
mvwadd_wch	window
mvwadd_wchnstr	window
mvwadd_wchstr	window
mvwaddch	window
mvwaddchnstr	window
mvwaddchstr	window
mvwaddnstr	window
mvwaddnwstr	window
mvwaddstr	window
mvwaddwstr	window
mvwchgat	window
mvwdelch	window
mvwget_wch	screen (input-operation)
mvwget_wstr	screen (input-operation)
mvwgetch	screen (input-operation)
mvwgetn_wstr	screen (input-operation)
mvwgetnstr	screen (input-operation)
mvwgetstr	screen (input-operation)
mvwhline	window
mvwhline_set	window
mvwin	window
mvwin_wch	window
mvwin_wchnstr	window
mvwin_wchstr	window
mvwinch	window
mvwinchnstr	window
mvwinchstr	window
mvwinnstr	window
mvwinnwstr	window
mvwins_nwstr	window
mvwins_wch	window
mvwins_wstr	window
mvwinsch	window
mvwinsnstr	window
mvwinsstr	window
mvwinstr	window
mvwinwstr	window
mvwprintw	window
mvwscanw	screen
mvwvline	window
mvwvline_set	window
napms	reentrant
newpad	global locks(windowlist)
newscr	screen (readonly)
newterm	global locks(screenlist)
newwin	global locks(windowlist)
nl	screen
nocbreak	screen
nodelay	window
noecho	screen
nofilter	global
nonl	screen
noqiflush	terminal
noraw	screen
notimeout	window
numcodes	global (readonly)
numfnames	global (readonly)
numnames	global (readonly)
ospeed	global
overlay	window locks(source, target)
overwrite	window locks(source, target)
pair_content	screen
pecho_wchar	screen
pechochar	screen
pnoutrefresh	screen
prefresh	screen
printw	window
putp	global
putwin	window
qiflush	terminal
raw	screen
redrawwin	window
refresh	screen
reset_prog_mode	screen
reset_shell_mode	screen
resetty	terminal
resize_term	screen locks(windowlist)
resizeterm	screen
restartterm	screen
ripoffline	global (static data)
savetty	terminal
scanw	screen
scr_dump	screen
scr_init	screen
scr_restore	screen
scr_set	screen
scrl	window (stdscr)
scroll	window
scrollok	window
set_curterm	screen
set_escdelay	screen
set_tabsize	screen
set_term	global locks(screenlist, screen)
setcchar	reentrant
setscrreg	window (stdscr)
setupterm	global
slk_attr	screen
slk_attr_off	screen
slk_attr_on	screen
slk_attr_set	screen
slk_attroff	screen
slk_attron	screen
slk_attrset	screen
slk_clear	screen
slk_color	screen
slk_init	screen
slk_label	screen
slk_noutrefresh	screen
slk_refresh	screen
slk_restore	screen
slk_set	screen
slk_touch	screen
slk_wset	screen
standend	window
standout	window
start_color	screen
stdscr	screen (readonly)
strcodes	global (readonly)
strfnames	global (readonly)
strnames	global (readonly)
subpad	window
subwin	window
syncok	window
term_attrs	screen
termattrs	screen
termname	terminal
tgetent	global
tgetflag	global
tgetnum	global
tgetstr	global
tgoto	global
tigetflag	terminal
tigetnum	terminal
tigetstr	terminal
timeout	window (stdscr)
touchline	window
touchwin	window
tparm	global (static data)
tputs	screen
trace	global (static data)
ttytype	screen (readonly)
typeahead	screen
unctrl	screen
unget_wch	screen (input-operation)
ungetch	screen (input-operation)
ungetmouse	screen (input-operation)
untouchwin	window
use_default_colors	screen
use_env	global (static data)
use_extended_names	global (static data)
use_legacy_coding	screen
use_screen	global locks(screenlist, screen)
use_window	global locks(windowlist, window)
vid_attr	screen
vid_puts	screen
vidattr	screen
vidputs	screen
vline	window (stdscr)
vline_set	window (stdscr)
vw_printw	window
vw_scanw	screen
vwprintw	window
vwscanw	screen
wadd_wch	window
wadd_wchnstr	window
wadd_wchstr	window
waddch	window
waddchnstr	window
waddchstr	window
waddnstr	window
waddnwstr	window
waddstr	window
waddwstr	window
wattr_get	window
wattr_off	window
wattr_on	window
wattr_set	window
wattroff	window
wattron	window
wattrset	window
wbkgd	window
wbkgdset	window
wbkgrnd	window
wbkgrndset	window
wborder	window
wborder_set	window
wchgat	window
wclear	window
wclrtobot	window
wclrtoeol	window
wcolor_set	window
wcursyncup	screen (affects window plus parents)
wdelch	window
wdeleteln	window
wecho_wchar	window
wechochar	window
wenclose	window
werase	window
wget_wch	screen (input-operation)
wget_wstr	screen (input-operation)
wgetbkgrnd	window
wgetch	screen (input-operation)
wgetdelay	window
wgetn_wstr	screen (input-operation)
wgetnstr	screen (input-operation)
wgetparent	window
wgetscrreg	window
wgetstr	screen (input-operation)
whline	window
whline_set	window
win_wch	window
win_wchnstr	window
win_wchstr	window
winch	window
winchnstr	window
winchstr	window
winnstr	window
winnwstr	window
wins_nwstr	window
wins_wch	window
wins_wstr	window
winsch	window
winsdelln	window
winsertln	window
winsnstr	window
winsstr	window
winstr	window
winwstr	window
wmouse_trafo	window
wmove	window
wnoutrefresh	screen
wprintw	window
wredrawln	window
wrefresh	screen
wresize	window locks(windowlist)
wscanw	screen
wscrl	window
wsetscrreg	window
wstandend	window
wstandout	window
wsyncdown	screen (affects window plus parents)
wsyncup	screen (affects window plus parents)
wtimeout	window
wtouchln	window
wunctrl	global (static data)
wvline	window
wvline_set	window

RETURN VALUE

These functions all return TRUE or FALSE, except as noted.

NOTES

Both a macro and a function are provided for each name.

PORTABILITY

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.