| '\" 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 @NCURSES_MAJOR@.@NCURSES_MINOR@" "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 <curses.h> |
| .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) |