'\" t .\"*************************************************************************** .\" Copyright 2021-2023,2024 Thomas E. Dickey * .\" Copyright 2008-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * .\" "Software"), to deal in the Software without restriction, including * .\" without limitation the rights to use, copy, modify, merge, publish, * .\" distribute, distribute with modifications, sublicense, and/or sell * .\" copies of the Software, and to permit persons to whom the Software is * .\" furnished to do so, subject to the following conditions: * .\" * .\" The above copyright notice and this permission notice shall be included * .\" in all copies or substantial portions of the Software. * .\" * .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * .\" * .\" Except as contained in this notice, the name(s) of the above copyright * .\" holders shall not be used in advertising or otherwise to promote the * .\" sale, use or other dealings in this Software without prior written * .\" authorization. * .\"*************************************************************************** .\" .\" $Id: curs_threads.3x,v 1.56 2024/03/16 15:35:01 tom Exp $ .TH curs_threads 3X 2024-03-16 "ncurses 6.5" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq .\} .el \{\ .ie t .ds `` `` .el .ds `` "" .ie t .ds '' '' .el .ds '' "" .\} . .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 .. .SH NAME \fI\%NCURSES_WINDOW_CB\fP, \fI\%NCURSES_SCREEN_CB\fP, \fB\%get_escdelay\fP, \fB\%set_escdelay\fP, \fB\%set_tabsize\fP, \fB\%use_screen\fP, \fB\%use_window\fP \- \fIcurses\fR support for multi-threaded applications .SH SYNOPSIS .nf \fB#include .PP \fI/* data types */ \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *); \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *); .PP \fBint get_escdelay(void); \fBint set_escdelay(int \fIms\fP); \fBint set_tabsize(int \fIcols\fP); .PP \fBint use_screen(SCREEN *\fIscr\fP, NCURSES_SCREEN_CB \fIfunc\fP, void *\fIdata\fP); \fBint use_window(WINDOW *\fIwin\fP, NCURSES_WINDOW_CB \fIfunc\fP, void *\fIdata\fP); .fi .SH DESCRIPTION The \fI\%ncurses\fP library can be configured to support multi-threaded applications in a rudimentary way. Such configuration produces a different set of libraries, named \fIlibncursest\fP, for example, since doing so alters \fI\%ncurses\fP's application binary interface (ABI). .PP Instead of modifying the programming interface (API) to make \fI\%ncurses\fP functions expect an additional argument specifying a thread, the library adds functions, usable in any configuration, that hide the \fImutexes\fP (mutual exclusion locks) needed to prevent concurrent access to variables shared by multiple threads of execution. .PP \fI\%ncurses\fP threading support requires the use of functions to access members of the \fI\%WINDOW\fP structure (see \fBcurs_opaque\fP(3X)). It further makes functions of the common global variables \fB\%COLORS\fP, \fB\%COLOR_PAIRS\fP, \fB\%COLS\fP, \fB\%ESCDELAY\fP, \fB\%LINES\fP, \fB\%TABSIZE\fP, \fB\%curscr\fP, \fB\%newscr\fP, and \fB\%ttytype\fP, maintaining them as as read-only values in the \fISCREEN\fP structure. .PP Even this is not enough to make an application using \fIcurses\fP 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. .PP The \fB\%ESCDELAY\fP and \fB\%TABSIZE\fP global variables are modified by some applications. To modify them in any configuration, use the \fB\%set_escdelay\fP or \fB\%set_tabsize\fP functions. Other global variables are not modifiable. \fBget_escdelay\fP retrieves \fB\%ESCDELAY\fP's value. .PP The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse-grained mutexes for their respective \fI\%WINDOW\fP and \fISCREEN\fP parameters; they call a user-supplied function, pass it a \fIdata\fP parameter, and return the value from the user-supplied function to the application. .\" *************************************************************************** .SS Usage All \fI\%ncurses\fP library functions assume that the locale is not altered during operation. In addition, they use data that is maintained within a hierarchy of scopes. .bP global data used in the low-level \fIterminfo\fP or \fItermcap\fP interfaces .bP terminal data associated with a call to \fBset_curterm\fP(3X) .IP Terminal data are initialized when screens are created. .bP screen data associated with a call to \fBnewterm\fP(3X) or \fBinitscr\fP(3X) .bP window data associated with a call to \fBnewwin\fP(3X) or \fBsubwin\fP(3X) .IP Windows are associated with screens. Pads are not necessarily associated with any particular screen. .IP Most \fIcurses\fP applications operate on one or more windows within a single screen. .bP reentrant data associated with \*(``pure\*('' functions that alter no shared variables .PP The following table lists the scope of each symbol in the \fI\%ncurses\fP library when configured to support multi-threaded applications. .PP .TS center; Lb2 Lb Lb2 Lx. Symbol Scope _ BC global COLORS screen (read-only) COLOR_PAIR reentrant COLOR_PAIRS screen (read-only) COLS screen (read-only) ESCDELAY screen (read-only; see \fBset_escdelay\fP) LINES screen (read-only) PAIR_NUMBER reentrant PC global SP global TABSIZE screen (read-only; see \fBset_tabsize\fP) UP global acs_map screen (read-only) add_wch window (\fBstdscr\fP) add_wchnstr window (\fBstdscr\fP) add_wchstr window (\fBstdscr\fP) addch window (\fBstdscr\fP) addchnstr window (\fBstdscr\fP) addchstr window (\fBstdscr\fP) addnstr window (\fBstdscr\fP) addnwstr window (\fBstdscr\fP) addstr window (\fBstdscr\fP) addwstr window (\fBstdscr\fP) assume_default_colors screen attr_get window (\fBstdscr\fP) attr_off window (\fBstdscr\fP) attr_on window (\fBstdscr\fP) attr_set window (\fBstdscr\fP) attroff window (\fBstdscr\fP) attron window (\fBstdscr\fP) attrset window (\fBstdscr\fP) baudrate screen beep screen bkgd window (\fBstdscr\fP) bkgdset window (\fBstdscr\fP) bkgrnd window (\fBstdscr\fP) bkgrndset window (\fBstdscr\fP) boolcodes global (read-only) boolfnames global (read-only) boolnames global (read-only) border window (\fBstdscr\fP) border_set window (\fBstdscr\fP) box window (\fBstdscr\fP) box_set window (\fBstdscr\fP) can_change_color terminal cbreak screen chgat window (\fBstdscr\fP) clear window (\fBstdscr\fP) clearok window clrtobot window (\fBstdscr\fP) clrtoeol window (\fBstdscr\fP) color_content screen color_set window (\fBstdscr\fP) copywin window (locks source, target) cur_term terminal curs_set screen curscr screen (read-only) curses_version global (read-only) def_prog_mode terminal def_shell_mode terminal define_key screen del_curterm screen delay_output screen delch window (\fBstdscr\fP) deleteln window (\fBstdscr\fP) delscreen global (locks screen list, screen) delwin global (locks window list) derwin screen doupdate screen dupwin screen (locks window) echo screen echo_wchar window (\fBstdscr\fP) echochar window (\fBstdscr\fP) endwin screen erase window (\fBstdscr\fP) erasechar window (\fBstdscr\fP) erasewchar window (\fBstdscr\fP) 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 (\fBstdscr\fP) hline_set window (\fBstdscr\fP) idcok window idlok window immedok window in_wch window (\fBstdscr\fP) in_wchnstr window (\fBstdscr\fP) in_wchstr window (\fBstdscr\fP) inch window (\fBstdscr\fP) inchnstr window (\fBstdscr\fP) inchstr window (\fBstdscr\fP) init_color screen init_pair screen initscr global (locks screen list) innstr window (\fBstdscr\fP) innwstr window (\fBstdscr\fP) ins_nwstr window (\fBstdscr\fP) ins_wch window (\fBstdscr\fP) ins_wstr window (\fBstdscr\fP) insch window (\fBstdscr\fP) insdelln window (\fBstdscr\fP) insertln window (\fBstdscr\fP) insnstr window (\fBstdscr\fP) insstr window (\fBstdscr\fP) instr window (\fBstdscr\fP) intrflush terminal inwstr window (\fBstdscr\fP) 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 (\fBstdscr\fP) mouseinterval screen mousemask screen move window (\fBstdscr\fP) mvadd_wch window (\fBstdscr\fP) mvadd_wchnstr window (\fBstdscr\fP) mvadd_wchstr window (\fBstdscr\fP) mvaddch window (\fBstdscr\fP) mvaddchnstr window (\fBstdscr\fP) mvaddchstr window (\fBstdscr\fP) mvaddnstr window (\fBstdscr\fP) mvaddnwstr window (\fBstdscr\fP) mvaddstr window (\fBstdscr\fP) mvaddwstr window (\fBstdscr\fP) mvchgat window (\fBstdscr\fP) mvcur screen mvdelch window (\fBstdscr\fP) mvderwin window (\fBstdscr\fP) 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 (\fBstdscr\fP) mvhline_set window (\fBstdscr\fP) mvin_wch window (\fBstdscr\fP) mvin_wchnstr window (\fBstdscr\fP) mvin_wchstr window (\fBstdscr\fP) mvinch window (\fBstdscr\fP) mvinchnstr window (\fBstdscr\fP) mvinchstr window (\fBstdscr\fP) mvinnstr window (\fBstdscr\fP) mvinnwstr window (\fBstdscr\fP) mvins_nwstr window (\fBstdscr\fP) mvins_wch window (\fBstdscr\fP) mvins_wstr window (\fBstdscr\fP) mvinsch window (\fBstdscr\fP) mvinsnstr window (\fBstdscr\fP) mvinsstr window (\fBstdscr\fP) mvinstr window (\fBstdscr\fP) mvinwstr window (\fBstdscr\fP) mvprintw window (\fBstdscr\fP) mvscanw screen mvvline window (\fBstdscr\fP) mvvline_set window (\fBstdscr\fP) 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 window list) newscr screen (read-only) newterm global (locks screen list) newwin global (locks window list) nl screen nocbreak screen nodelay window noecho screen nofilter global nonl screen noqiflush terminal noraw screen notimeout window numcodes global (read-only) numfnames global (read-only) numnames global (read-only) 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 window list) 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 (\fBstdscr\fP) scroll window scrollok window set_curterm screen set_escdelay screen set_tabsize screen set_term global (locks screen list, screen) setcchar reentrant setscrreg window (\fBstdscr\fP) 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 \fBstdscr\fP screen (read-only) strcodes global (read-only) strfnames global (read-only) strnames global (read-only) 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 (\fBstdscr\fP) touchline window touchwin window tparm global (static data) tputs screen trace global (static data) ttytype screen (read-only) 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 screen list, screen) use_window global (locks window list, window) vid_attr screen vid_puts screen vidattr screen vidputs screen vline window (\fBstdscr\fP) vline_set window (\fBstdscr\fP) 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 window list) 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 .TE .\" *************************************************************************** .SH RETURN VALUE \fB\%get_escdelay\fP returns the value of \fB\%ESCDELAY\fP. \fB\%set_escdelay\fP and \fB\%set_tabsize\fP return \fBERR\fP upon failure and \fBOK\fP upon successful completion. \fB\%use_screen\fP and \fB\%use_window\fP return the \fIint\fP returned by the user-supplied function they are called with. .SH NOTES \fI\%ncurses\fP provides both a C function and a preprocessor macro for each function documented in this page. .SH PORTABILITY These routines are specific to \fI\%ncurses\fP. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on \fI\%ncurses\fP extensions be conditioned using \fB\%NCURSES_VERSION\fP. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_opaque\fP(3X), \fB\%curs_variables\fP(3X)