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 $
***************************************************************************
***************************************************************************
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 $
curs_threads 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.\}
.\}
.
..
NAME
\%NCURSES_WINDOW_CB,
\%NCURSES_SCREEN_CB,
\%get_escdelay,
\%set_escdelay,
\%set_tabsize,
\%use_screen,
\%use_window -
curses support for multi-threaded applications
SYNOPSIS
#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);
DESCRIPTION
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.
***************************************************************************
Usage
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.
.bP
global data used in the low-level terminfo or termcap
interfaces
.bP
terminal data associated with a call to set_curterm(3X)
Terminal data are initialized when screens are created.
.bP
screen data associated with a call to newterm(3X) or
initscr(3X)
.bP
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.
.bP
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.
| 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 set_escdelay) |
| LINES screen (read-only) |
| PAIR_NUMBER reentrant |
| PC global |
| SP global |
| TABSIZE screen (read-only; see set_tabsize) |
| UP global |
| acs_map screen (read-only) |
| 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 (read-only) |
| boolfnames global (read-only) |
| boolnames global (read-only) |
| 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 (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 (stdscr) |
| deleteln window (stdscr) |
| delscreen global (locks screen list, screen) |
| delwin global (locks window list) |
| 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 screen list) |
| 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 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 (stdscr) |
| scroll window |
| scrollok window |
| set_curterm screen |
| set_escdelay screen |
| set_tabsize screen |
| set_term global (locks screen list, 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 (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 (stdscr) |
| 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 (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 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 |
RETURN VALUE
\%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.
NOTES
\%ncurses provides both a C function and a preprocessor macro for
each function documented in this page.
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.
SEE ALSO
\%curses(3X),
\%curs_opaque(3X),
\%curs_variables(3X)