'\" t .\"*************************************************************************** .\" Copyright 2021-2022,2023 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.3,v 1.1 2023/10/17 09:52:08 nicm Exp $ .TH curs_threads 3 2023-08-19 "ncurses 6.4" "Library calls" .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 .. .na .hy 0 .SH NAME \fBcurs_threads\fP \- \fBcurses\fP thread support .ad .hy .SH SYNOPSIS \fB#include \fP .sp \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fP .br \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fP .sp \fBint get_escdelay(void);\fP .br \fBint set_escdelay(int \fIms\fB);\fR .br \fBint set_tabsize(int \fIcols\fB);\fR .sp \fBint use_screen(SCREEN *\fIscr\fB, NCURSES_SCREEN_CB \fIfunc\fB, void *\fIdata\fB);\fR .br \fBint use_window(WINDOW *\fIwin\fB, NCURSES_WINDOW_CB \fIfunc\fB, void *\fIdata\fB);\fR .SH DESCRIPTION This implementation can be configured to provide rudimentary support for multi-threaded applications. This makes a different set of libraries, e.g., \fBlibncursest\fP since the binary interfaces are different. .PP 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. .PP In addition to forcing access to members of the \fBWINDOW\fP structure to be via functions (see \fBcurs_opaque\fP(3)), 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 \fBSCREEN\fP structure. .PP 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. .PP The ESCDELAY and TABSIZE global variables are modified by some applications. To modify them in any configuration, use the \fBset_escdelay\fP or \fBset_tabsize\fP functions. Other global variables are not modifiable. .PP The \fBget_escdelay\fP function returns the value for ESCDELAY. .PP The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP parameters, and call a user-supplied function, passing it a \fIdata\fP parameter, and returning the value from the user-supplied function to the application. .\" *************************************************************************** .SS 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. .RS 3 .bP global data, e.g., used in the low-level terminfo or termcap interfaces. .bP terminal data, e.g., associated with a call to \fBset_curterm\fP. The terminal data are initialized when screens are created. .bP screen data, e.g., associated with a call to \fBnewterm\fP or \fBinitscr\fP. .bP window data, e.g., associated with a call to \fBnewwin\fP or \fBsubwin\fP. Windows are associated with screens. Pads are not necessarily associated with a particular screen. .IP Most curses applications operate on one or more windows within a single screen. .bP reentrant, i.e., it uses only the data passed as parameters. .RE .PP This table lists the scope of data used for each symbol in the ncurses library when it is configured to support threading: .PP .TS center tab(/); l l l l . Symbol/Scope = BC/global COLORS/screen (readonly) COLOR_PAIR/reentrant COLOR_PAIRS/screen (readonly) COLS/screen (readonly) ESCDELAY/screen (readonly, see \fBset_escdelay\fP) 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 .TE .\" *************************************************************************** .SH RETURN VALUE These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted. .SH NOTES Both a macro and a function are provided for each name. .SH 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. .SH SEE ALSO \fBcurses\fP(3), \fBcurs_opaque\fP(3), \fBcurs_variables\fP(3).