1 .\"***************************************************************************
2 .\" Copyright 2021,2022 Thomas E. Dickey *
3 .\" Copyright 2008-2015,2017 Free Software Foundation, Inc. *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
28 .\"***************************************************************************
30 .\" $Id: curs_threads.3x,v 1.31 2022/02/12 20:05:11 tom Exp $
31 .TH curs_threads 3X ""
39 \fBcurs_threads\fP \- \fBcurses\fP thread support
43 \fB#include <curses.h>\fP
45 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fP
47 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fP
49 \fBint get_escdelay(void);\fP
51 \fBint set_escdelay(int \fIms\fB);\fR
53 \fBint set_tabsize(int \fIcols\fB);\fR
55 \fBint use_screen(SCREEN *\fIscr\fB, NCURSES_SCREEN_CB \fIfunc\fB, void *\fIdata\fB);\fR
57 \fBint use_window(WINDOW *\fIwin\fB, NCURSES_WINDOW_CB \fIfunc\fB, void *\fIdata\fB);\fR
60 This implementation can be configured to provide rudimentary support
61 for multi-threaded applications.
62 This makes a different set of libraries, e.g., \fBlibncursest\fP since
63 the binary interfaces are different.
65 Rather than modify the interfaces to pass a thread specifier to
66 each function, it adds a few functions which can be used in any
67 configuration which hide the mutex's needed to prevent concurrent
68 use of the global variables when configured for threading.
70 In addition to forcing access to members of the \fBWINDOW\fP structure
71 to be via functions (see \fBcurs_opaque\fP(3X)),
72 it makes functions of the common global variables,
83 Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
86 Even this is not enough to make a thread-safe application using curses.
87 A multi-threaded application would be expected to have threads updating
88 separate windows (within the same device),
89 or updating on separate screens (on different devices).
90 Also, a few of the global variables are considered writable by some
92 The functions described here address these special situations.
94 The ESCDELAY and TABSIZE global variables are modified by some applications.
95 To modify them in any configuration,
96 use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
97 Other global variables are not modifiable.
99 The \fBget_escdelay\fP function returns the value for ESCDELAY.
101 The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
102 granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
103 parameters, and call a user-supplied function,
104 passing it a \fIdata\fP parameter,
105 and returning the value from the user-supplied function to the application.
106 .\" ***************************************************************************
108 All of the ncurses library functions assume that the locale is not
109 altered during operation.
111 they use data which is maintained within a hierarchy of scopes.
114 global data, e.g., used in the low-level terminfo or termcap interfaces.
116 terminal data, e.g., associated with a call to \fBset_curterm\fP.
117 The terminal data are initialized when screens are created.
119 screen data, e.g., associated with a call to \fBnewterm\fP or \fBinitscr\fP.
121 window data, e.g., associated with a call to \fBnewwin\fP or \fBsubwin\fP.
122 Windows are associated with screens.
123 Pads are not necessarily associated with a particular screen.
125 Most curses applications operate on one or more windows within a single screen.
127 reentrant, i.e., it uses only the data passed as parameters.
130 This table lists the scope of data used for each symbol in the
131 ncurses library when it is configured to support threading:
139 COLORS/screen (readonly)
141 COLOR_PAIRS/screen (readonly)
142 COLS/screen (readonly)
143 ESCDELAY/screen (readonly, see \fBset_escdelay\fP)
144 LINES/screen (readonly)
145 PAIR_NUMBER/reentrant
148 TABSIZE/screen (readonly)
150 acs_map/screen (readonly)
151 add_wch/window (stdscr)
152 add_wchnstr/window (stdscr)
153 add_wchstr/window (stdscr)
154 addch/window (stdscr)
155 addchnstr/window (stdscr)
156 addchstr/window (stdscr)
157 addnstr/window (stdscr)
158 addnwstr/window (stdscr)
159 addstr/window (stdscr)
160 addwstr/window (stdscr)
161 assume_default_colors/screen
162 attr_get/window (stdscr)
163 attr_off/window (stdscr)
164 attr_on/window (stdscr)
165 attr_set/window (stdscr)
166 attroff/window (stdscr)
167 attron/window (stdscr)
168 attrset/window (stdscr)
172 bkgdset/window (stdscr)
173 bkgrnd/window (stdscr)
174 bkgrndset/window (stdscr)
175 boolcodes/global (readonly)
176 boolfnames/global (readonly)
177 boolnames/global (readonly)
178 border/window (stdscr)
179 border_set/window (stdscr)
181 box_set/window (stdscr)
182 can_change_color/terminal
184 chgat/window (stdscr)
185 clear/window (stdscr)
187 clrtobot/window (stdscr)
188 clrtoeol/window (stdscr)
190 color_set/window (stdscr)
191 copywin/window locks(source, target)
194 curscr/screen (readonly)
195 curses_version/global (readonly)
196 def_prog_mode/terminal
197 def_shell_mode/terminal
201 delch/window (stdscr)
202 deleteln/window (stdscr)
203 delscreen/global locks(screenlist, screen)
204 delwin/global locks(windowlist)
207 dupwin/screen locks(window)
209 echo_wchar/window (stdscr)
210 echochar/window (stdscr)
212 erase/window (stdscr)
213 erasechar/window (stdscr)
214 erasewchar/window (stdscr)
218 get_wch/screen (input-operation)
219 get_wstr/screen (input-operation)
226 getch/screen (input-operation)
231 getmouse/screen (input-operation)
232 getn_wstr/screen (input-operation)
233 getnstr/screen (input-operation)
236 getstr/screen (input-operation)
237 getwin/screen (input-operation)
243 hline/window (stdscr)
244 hline_set/window (stdscr)
248 in_wch/window (stdscr)
249 in_wchnstr/window (stdscr)
250 in_wchstr/window (stdscr)
252 inchnstr/window (stdscr)
253 inchstr/window (stdscr)
256 initscr/global locks(screenlist)
257 innstr/window (stdscr)
258 innwstr/window (stdscr)
259 ins_nwstr/window (stdscr)
260 ins_wch/window (stdscr)
261 ins_wstr/window (stdscr)
262 insch/window (stdscr)
263 insdelln/window (stdscr)
264 insertln/window (stdscr)
265 insnstr/window (stdscr)
266 insstr/window (stdscr)
267 instr/window (stdscr)
269 inwstr/window (stdscr)
276 is_linetouched/window
281 is_term_resized/terminal
285 key_name/global (static data)
287 keyname/global (static data)
296 mouse_trafo/window (stdscr)
300 mvadd_wch/window (stdscr)
301 mvadd_wchnstr/window (stdscr)
302 mvadd_wchstr/window (stdscr)
303 mvaddch/window (stdscr)
304 mvaddchnstr/window (stdscr)
305 mvaddchstr/window (stdscr)
306 mvaddnstr/window (stdscr)
307 mvaddnwstr/window (stdscr)
308 mvaddstr/window (stdscr)
309 mvaddwstr/window (stdscr)
310 mvchgat/window (stdscr)
312 mvdelch/window (stdscr)
313 mvderwin/window (stdscr)
314 mvget_wch/screen (input-operation)
315 mvget_wstr/screen (input-operation)
316 mvgetch/screen (input-operation)
317 mvgetn_wstr/screen (input-operation)
318 mvgetnstr/screen (input-operation)
319 mvgetstr/screen (input-operation)
320 mvhline/window (stdscr)
321 mvhline_set/window (stdscr)
322 mvin_wch/window (stdscr)
323 mvin_wchnstr/window (stdscr)
324 mvin_wchstr/window (stdscr)
325 mvinch/window (stdscr)
326 mvinchnstr/window (stdscr)
327 mvinchstr/window (stdscr)
328 mvinnstr/window (stdscr)
329 mvinnwstr/window (stdscr)
330 mvins_nwstr/window (stdscr)
331 mvins_wch/window (stdscr)
332 mvins_wstr/window (stdscr)
333 mvinsch/window (stdscr)
334 mvinsnstr/window (stdscr)
335 mvinsstr/window (stdscr)
336 mvinstr/window (stdscr)
337 mvinwstr/window (stdscr)
338 mvprintw/window (stdscr)
340 mvvline/window (stdscr)
341 mvvline_set/window (stdscr)
343 mvwadd_wchnstr/window
354 mvwget_wch/screen (input-operation)
355 mvwget_wstr/screen (input-operation)
356 mvwgetch/screen (input-operation)
357 mvwgetn_wstr/screen (input-operation)
358 mvwgetnstr/screen (input-operation)
359 mvwgetstr/screen (input-operation)
384 newpad/global locks(windowlist)
385 newscr/screen (readonly)
386 newterm/global locks(screenlist)
387 newwin/global locks(windowlist)
397 numcodes/global (readonly)
398 numfnames/global (readonly)
399 numnames/global (readonly)
401 overlay/window locks(source, target)
402 overwrite/window locks(source, target)
415 reset_prog_mode/screen
416 reset_shell_mode/screen
418 resize_term/screen locks(windowlist)
421 ripoffline/global (static data)
434 set_term/global locks(screenlist, screen)
436 setscrreg/window (stdscr)
449 slk_noutrefresh/screen
458 stdscr/screen (readonly)
459 strcodes/global (readonly)
460 strfnames/global (readonly)
461 strnames/global (readonly)
476 timeout/window (stdscr)
479 tparm/global (static data)
481 trace/global (static data)
482 ttytype/screen (readonly)
485 unget_wch/screen (input-operation)
486 ungetch/screen (input-operation)
487 ungetmouse/screen (input-operation)
489 use_default_colors/screen
490 use_env/global (static data)
491 use_extended_names/global (static data)
492 use_legacy_coding/screen
493 use_screen/global locks(screenlist, screen)
494 use_window/global locks(windowlist, window)
499 vline/window (stdscr)
500 vline_set/window (stdscr)
533 wcursyncup/screen (affects window plus parents)
540 wget_wch/screen (input-operation)
541 wget_wstr/screen (input-operation)
543 wgetch/screen (input-operation)
545 wgetn_wstr/screen (input-operation)
546 wgetnstr/screen (input-operation)
549 wgetstr/screen (input-operation)
576 wresize/window locks(windowlist)
582 wsyncdown/screen (affects window plus parents)
583 wsyncup/screen (affects window plus parents)
586 wunctrl/global (static data)
590 .\" ***************************************************************************
592 These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
594 Both a macro and a function are provided for each name.
596 These routines are specific to ncurses.
597 They were not supported on Version 7, BSD or System V implementations.
598 It is recommended that any code depending on ncurses extensions
599 be conditioned using NCURSES_VERSION.
602 \fBcurs_opaque\fP(3X),
603 \fBcurs_variables\fP(3X).