use_window(3) curses thread support

Other Alias

use_screen

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:

SymbolScope


BCglobal
COLORSscreen (readonly)
COLOR_PAIRreentrant
COLOR_PAIRSscreen (readonly)
COLSscreen (readonly)
ESCDELAYscreen (readonly, see set_escdelay)
LINESscreen (readonly)
PAIR_NUMBERreentrant
PCglobal
SPglobal
TABSIZEscreen (readonly)
UPglobal
acs_mapscreen (readonly)
add_wchwindow (stdscr)
add_wchnstrwindow (stdscr)
add_wchstrwindow (stdscr)
addchwindow (stdscr)
addchnstrwindow (stdscr)
addchstrwindow (stdscr)
addnstrwindow (stdscr)
addnwstrwindow (stdscr)
addstrwindow (stdscr)
addwstrwindow (stdscr)
assume_default_colorsscreen
attr_getwindow (stdscr)
attr_offwindow (stdscr)
attr_onwindow (stdscr)
attr_setwindow (stdscr)
attroffwindow (stdscr)
attronwindow (stdscr)
attrsetwindow (stdscr)
baudratescreen
beepscreen
bkgdwindow (stdscr)
bkgdsetwindow (stdscr)
bkgrndwindow (stdscr)
bkgrndsetwindow (stdscr)
boolcodesglobal (readonly)
boolfnamesglobal (readonly)
boolnamesglobal (readonly)
borderwindow (stdscr)
border_setwindow (stdscr)
boxwindow (stdscr)
box_setwindow (stdscr)
can_change_colorterminal
cbreakscreen
chgatwindow (stdscr)
clearwindow (stdscr)
clearokwindow
clrtobotwindow (stdscr)
clrtoeolwindow (stdscr)
color_contentscreen
color_setwindow (stdscr)
copywinwindow locks(source, target)
cur_termterminal
curs_setscreen
curscrscreen (readonly)
curses_versionglobal (readonly)
def_prog_modeterminal
def_shell_modeterminal
define_keyscreen
del_curtermscreen
delay_outputscreen
delchwindow (stdscr)
deletelnwindow (stdscr)
delscreenglobal locks(screenlist, screen)
delwinglobal locks(windowlist)
derwinscreen
doupdatescreen
dupwinscreen locks(window)
echoscreen
echo_wcharwindow (stdscr)
echocharwindow (stdscr)
endwinscreen
erasewindow (stdscr)
erasecharwindow (stdscr)
erasewcharwindow (stdscr)
filterglobal
flashterminal
flushinpscreen
get_wchscreen (input-operation)
get_wstrscreen (input-operation)
getattrswindow
getbegxwindow
getbegywindow
getbkgdwindow
getbkgrndwindow
getccharreentrant
getchscreen (input-operation)
getcurxwindow
getcurywindow
getmaxxwindow
getmaxywindow
getmousescreen (input-operation)
getn_wstrscreen (input-operation)
getnstrscreen (input-operation)
getparxwindow
getparywindow
getstrscreen (input-operation)
getwinscreen (input-operation)
halfdelayscreen
has_colorsterminal
has_icterminal
has_ilterminal
has_keyscreen
hlinewindow (stdscr)
hline_setwindow (stdscr)
idcokwindow
idlokwindow
immedokwindow
in_wchwindow (stdscr)
in_wchnstrwindow (stdscr)
in_wchstrwindow (stdscr)
inchwindow (stdscr)
inchnstrwindow (stdscr)
inchstrwindow (stdscr)
init_colorscreen
init_pairscreen
initscrglobal locks(screenlist)
innstrwindow (stdscr)
innwstrwindow (stdscr)
ins_nwstrwindow (stdscr)
ins_wchwindow (stdscr)
ins_wstrwindow (stdscr)
inschwindow (stdscr)
insdellnwindow (stdscr)
insertlnwindow (stdscr)
insnstrwindow (stdscr)
insstrwindow (stdscr)
instrwindow (stdscr)
intrflushterminal
inwstrwindow (stdscr)
is_clearedwindow
is_idcokwindow
is_idlokwindow
is_immedokwindow
is_keypadwindow
is_leaveokwindow
is_linetouchedwindow
is_nodelaywindow
is_notimeoutwindow
is_scrollokwindow
is_syncokwindow
is_term_resizedterminal
is_wintouchedwindow
isendwinscreen
key_definedscreen
key_nameglobal (static data)
keyboundscreen
keynameglobal (static data)
keyokscreen
keypadwindow
killcharterminal
killwcharterminal
leaveokwindow
longnamescreen
mcprintterminal
metascreen
mouse_trafowindow (stdscr)
mouseintervalscreen
mousemaskscreen
movewindow (stdscr)
mvadd_wchwindow (stdscr)
mvadd_wchnstrwindow (stdscr)
mvadd_wchstrwindow (stdscr)
mvaddchwindow (stdscr)
mvaddchnstrwindow (stdscr)
mvaddchstrwindow (stdscr)
mvaddnstrwindow (stdscr)
mvaddnwstrwindow (stdscr)
mvaddstrwindow (stdscr)
mvaddwstrwindow (stdscr)
mvchgatwindow (stdscr)
mvcurscreen
mvdelchwindow (stdscr)
mvderwinwindow (stdscr)
mvget_wchscreen (input-operation)
mvget_wstrscreen (input-operation)
mvgetchscreen (input-operation)
mvgetn_wstrscreen (input-operation)
mvgetnstrscreen (input-operation)
mvgetstrscreen (input-operation)
mvhlinewindow (stdscr)
mvhline_setwindow (stdscr)
mvin_wchwindow (stdscr)
mvin_wchnstrwindow (stdscr)
mvin_wchstrwindow (stdscr)
mvinchwindow (stdscr)
mvinchnstrwindow (stdscr)
mvinchstrwindow (stdscr)
mvinnstrwindow (stdscr)
mvinnwstrwindow (stdscr)
mvins_nwstrwindow (stdscr)
mvins_wchwindow (stdscr)
mvins_wstrwindow (stdscr)
mvinschwindow (stdscr)
mvinsnstrwindow (stdscr)
mvinsstrwindow (stdscr)
mvinstrwindow (stdscr)
mvinwstrwindow (stdscr)
mvprintwwindow (stdscr)
mvscanwscreen
mvvlinewindow (stdscr)
mvvline_setwindow (stdscr)
mvwadd_wchwindow
mvwadd_wchnstrwindow
mvwadd_wchstrwindow
mvwaddchwindow
mvwaddchnstrwindow
mvwaddchstrwindow
mvwaddnstrwindow
mvwaddnwstrwindow
mvwaddstrwindow
mvwaddwstrwindow
mvwchgatwindow
mvwdelchwindow
mvwget_wchscreen (input-operation)
mvwget_wstrscreen (input-operation)
mvwgetchscreen (input-operation)
mvwgetn_wstrscreen (input-operation)
mvwgetnstrscreen (input-operation)
mvwgetstrscreen (input-operation)
mvwhlinewindow
mvwhline_setwindow
mvwinwindow
mvwin_wchwindow
mvwin_wchnstrwindow
mvwin_wchstrwindow
mvwinchwindow
mvwinchnstrwindow
mvwinchstrwindow
mvwinnstrwindow
mvwinnwstrwindow
mvwins_nwstrwindow
mvwins_wchwindow
mvwins_wstrwindow
mvwinschwindow
mvwinsnstrwindow
mvwinsstrwindow
mvwinstrwindow
mvwinwstrwindow
mvwprintwwindow
mvwscanwscreen
mvwvlinewindow
mvwvline_setwindow
napmsreentrant
newpadglobal locks(windowlist)
newscrscreen (readonly)
newtermglobal locks(screenlist)
newwinglobal locks(windowlist)
nlscreen
nocbreakscreen
nodelaywindow
noechoscreen
nofilterglobal
nonlscreen
noqiflushterminal
norawscreen
notimeoutwindow
numcodesglobal (readonly)
numfnamesglobal (readonly)
numnamesglobal (readonly)
ospeedglobal
overlaywindow locks(source, target)
overwritewindow locks(source, target)
pair_contentscreen
pecho_wcharscreen
pechocharscreen
pnoutrefreshscreen
prefreshscreen
printwwindow
putpglobal
putwinwindow
qiflushterminal
rawscreen
redrawwinwindow
refreshscreen
reset_prog_modescreen
reset_shell_modescreen
resettyterminal
resize_termscreen locks(windowlist)
resizetermscreen
restarttermscreen
ripofflineglobal (static data)
savettyterminal
scanwscreen
scr_dumpscreen
scr_initscreen
scr_restorescreen
scr_setscreen
scrlwindow (stdscr)
scrollwindow
scrollokwindow
set_curtermscreen
set_escdelayscreen
set_tabsizescreen
set_termglobal locks(screenlist, screen)
setccharreentrant
setscrregwindow (stdscr)
setuptermglobal
slk_attrscreen
slk_attr_offscreen
slk_attr_onscreen
slk_attr_setscreen
slk_attroffscreen
slk_attronscreen
slk_attrsetscreen
slk_clearscreen
slk_colorscreen
slk_initscreen
slk_labelscreen
slk_noutrefreshscreen
slk_refreshscreen
slk_restorescreen
slk_setscreen
slk_touchscreen
slk_wsetscreen
standendwindow
standoutwindow
start_colorscreen
stdscrscreen (readonly)
strcodesglobal (readonly)
strfnamesglobal (readonly)
strnamesglobal (readonly)
subpadwindow
subwinwindow
syncokwindow
term_attrsscreen
termattrsscreen
termnameterminal
tgetentglobal
tgetflagglobal
tgetnumglobal
tgetstrglobal
tgotoglobal
tigetflagterminal
tigetnumterminal
tigetstrterminal
timeoutwindow (stdscr)
touchlinewindow
touchwinwindow
tparmglobal (static data)
tputsscreen
traceglobal (static data)
ttytypescreen (readonly)
typeaheadscreen
unctrlscreen
unget_wchscreen (input-operation)
ungetchscreen (input-operation)
ungetmousescreen (input-operation)
untouchwinwindow
use_default_colorsscreen
use_envglobal (static data)
use_extended_namesglobal (static data)
use_legacy_codingscreen
use_screenglobal locks(screenlist, screen)
use_windowglobal locks(windowlist, window)
vid_attrscreen
vid_putsscreen
vidattrscreen
vidputsscreen
vlinewindow (stdscr)
vline_setwindow (stdscr)
vw_printwwindow
vw_scanwscreen
vwprintwwindow
vwscanwscreen
wadd_wchwindow
wadd_wchnstrwindow
wadd_wchstrwindow
waddchwindow
waddchnstrwindow
waddchstrwindow
waddnstrwindow
waddnwstrwindow
waddstrwindow
waddwstrwindow
wattr_getwindow
wattr_offwindow
wattr_onwindow
wattr_setwindow
wattroffwindow
wattronwindow
wattrsetwindow
wbkgdwindow
wbkgdsetwindow
wbkgrndwindow
wbkgrndsetwindow
wborderwindow
wborder_setwindow
wchgatwindow
wclearwindow
wclrtobotwindow
wclrtoeolwindow
wcolor_setwindow
wcursyncupscreen (affects window plus parents)
wdelchwindow
wdeletelnwindow
wecho_wcharwindow
wechocharwindow
wenclosewindow
werasewindow
wget_wchscreen (input-operation)
wget_wstrscreen (input-operation)
wgetbkgrndwindow
wgetchscreen (input-operation)
wgetdelaywindow
wgetn_wstrscreen (input-operation)
wgetnstrscreen (input-operation)
wgetparentwindow
wgetscrregwindow
wgetstrscreen (input-operation)
whlinewindow
whline_setwindow
win_wchwindow
win_wchnstrwindow
win_wchstrwindow
winchwindow
winchnstrwindow
winchstrwindow
winnstrwindow
winnwstrwindow
wins_nwstrwindow
wins_wchwindow
wins_wstrwindow
winschwindow
winsdellnwindow
winsertlnwindow
winsnstrwindow
winsstrwindow
winstrwindow
winwstrwindow
wmouse_trafowindow
wmovewindow
wnoutrefreshscreen
wprintwwindow
wredrawlnwindow
wrefreshscreen
wresizewindow locks(windowlist)
wscanwscreen
wscrlwindow
wsetscrregwindow
wstandendwindow
wstandoutwindow
wsyncdownscreen (affects window plus parents)
wsyncupscreen (affects window plus parents)
wtimeoutwindow
wtouchlnwindow
wunctrlglobal (static data)
wvlinewindow
wvline_setwindow

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.