2 .\"***************************************************************************
3 .\" Copyright 2021-2022,2023 Thomas E. Dickey *
4 .\" Copyright 2008-2015,2017 Free Software Foundation, Inc. *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
29 .\"***************************************************************************
31 .\" $Id: curs_threads.3x,v 1.50 2023/12/16 20:32:22 tom Exp $
32 .TH curs_threads 3X 2023-12-16 "ncurses 6.4" "Library calls"
49 \fI\%NCURSES_WINDOW_CB\fP,
50 \fI\%NCURSES_SCREEN_CB\fP,
56 \fIcurses\fR support for multi-threaded applications
59 \fB#include <curses.h>
62 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
63 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);
65 \fBint get_escdelay(void);
66 \fBint set_escdelay(int \fIms\fP);
67 \fBint set_tabsize(int \fIcols\fP);
69 \fBint use_screen(SCREEN *\fIscr\fP, NCURSES_SCREEN_CB \fIfunc\fP, void *\fIdata\fP);
70 \fBint use_window(WINDOW *\fIwin\fP, NCURSES_WINDOW_CB \fIfunc\fP, void *\fIdata\fP);
73 The \fI\%ncurses\fP library can be configured to support multi-threaded
74 applications in a rudimentary way.
75 Such configuration produces a different set of libraries,
76 named \fIlibncursest\fP,
78 since doing so alters \fI\%ncurses\fP's application binary interface
81 Instead of modifying the programming interface (API) to make
82 \fI\%ncurses\fP functions expect an additional argument specifying a
84 the library adds functions,
85 usable in any configuration,
86 that hide the \fImutexes\fP
87 (mutual exclusion locks)
88 needed to prevent concurrent access to variables shared by multiple
91 \fI\%ncurses\fP threading support requires the use of functions to
92 access members of the \fI\%WINDOW\fP structure (see
93 \fBcurs_opaque\fP(3X)).
94 It further makes functions of the common global variables
105 maintaining them as as read-only values in the \fISCREEN\fP structure.
107 Even this is not enough to make an application using \fIcurses\fP
109 We would expect a multi-threaded application to have threads updating
110 separate windows (on the same device),
111 and separate screens (on different devices).
113 applications expect a few of the global variables to be writable.
114 The functions described here address these special situations.
116 The \fB\%ESCDELAY\fP and \fB\%TABSIZE\fP global variables are modified
117 by some applications.
118 To modify them in any configuration,
119 use the \fB\%set_escdelay\fP or \fB\%set_tabsize\fP functions.
120 Other global variables are not modifiable.
121 \fBget_escdelay\fP retrieves \fB\%ESCDELAY\fP's value.
123 The \fBuse_window\fP and \fBuse_screen\fP functions provide
124 coarse-grained mutexes for their respective \fI\%WINDOW\fP and
125 \fI\%SCREEN\fP parameters;
126 they call a user-supplied function,
127 pass it a \fIdata\fP parameter,
128 and return the value from the user-supplied function to the application.
129 .\" ***************************************************************************
131 All \fI\%ncurses\fP library functions assume that the locale is not
132 altered during operation.
134 they use data that is maintained within a hierarchy of scopes.
136 global data used in the low-level \fIterminfo\fP or \fItermcap\fP
139 terminal data associated with a call to \fBset_curterm\fP(3X)
141 Terminal data are initialized when screens are created.
143 screen data associated with a call to \fBnewterm\fP(3X) or
146 window data associated with a call to \fBnewwin\fP(3X) or
149 Windows are associated with screens.
150 Pads are not necessarily associated with any particular screen.
152 Most \fIcurses\fP applications operate on one or more windows within a
155 reentrant data associated with \*(``pure\*('' functions that alter no
158 The following table lists the scope of each symbol in the
159 \fI\%ncurses\fP library when configured to support multi-threaded
169 COLORS/screen (read-only)
171 COLOR_PAIRS/screen (read-only)
172 COLS/screen (read-only)
173 ESCDELAY/screen (read-only; see \fBset_escdelay\fP)
174 LINES/screen (read-only)
175 PAIR_NUMBER/reentrant
178 TABSIZE/screen (read-only; see \fBset_tabsize\fP)
180 acs_map/screen (read-only)
181 add_wch/window (\fBstdscr\fP)
182 add_wchnstr/window (\fBstdscr\fP)
183 add_wchstr/window (\fBstdscr\fP)
184 addch/window (\fBstdscr\fP)
185 addchnstr/window (\fBstdscr\fP)
186 addchstr/window (\fBstdscr\fP)
187 addnstr/window (\fBstdscr\fP)
188 addnwstr/window (\fBstdscr\fP)
189 addstr/window (\fBstdscr\fP)
190 addwstr/window (\fBstdscr\fP)
191 assume_default_colors/screen
192 attr_get/window (\fBstdscr\fP)
193 attr_off/window (\fBstdscr\fP)
194 attr_on/window (\fBstdscr\fP)
195 attr_set/window (\fBstdscr\fP)
196 attroff/window (\fBstdscr\fP)
197 attron/window (\fBstdscr\fP)
198 attrset/window (\fBstdscr\fP)
201 bkgd/window (\fBstdscr\fP)
202 bkgdset/window (\fBstdscr\fP)
203 bkgrnd/window (\fBstdscr\fP)
204 bkgrndset/window (\fBstdscr\fP)
205 boolcodes/global (read-only)
206 boolfnames/global (read-only)
207 boolnames/global (read-only)
208 border/window (\fBstdscr\fP)
209 border_set/window (\fBstdscr\fP)
210 box/window (\fBstdscr\fP)
211 box_set/window (\fBstdscr\fP)
212 can_change_color/terminal
214 chgat/window (\fBstdscr\fP)
215 clear/window (\fBstdscr\fP)
217 clrtobot/window (\fBstdscr\fP)
218 clrtoeol/window (\fBstdscr\fP)
220 color_set/window (\fBstdscr\fP)
221 copywin/window (locks source, target)
224 curscr/screen (read-only)
225 curses_version/global (read-only)
226 def_prog_mode/terminal
227 def_shell_mode/terminal
231 delch/window (\fBstdscr\fP)
232 deleteln/window (\fBstdscr\fP)
233 delscreen/global (locks screen list, screen)
234 delwin/global (locks window list)
237 dupwin/screen (locks window)
239 echo_wchar/window (\fBstdscr\fP)
240 echochar/window (\fBstdscr\fP)
242 erase/window (\fBstdscr\fP)
243 erasechar/window (\fBstdscr\fP)
244 erasewchar/window (\fBstdscr\fP)
248 get_wch/screen (input operation)
249 get_wstr/screen (input operation)
256 getch/screen (input operation)
261 getmouse/screen (input operation)
262 getn_wstr/screen (input operation)
263 getnstr/screen (input operation)
266 getstr/screen (input operation)
267 getwin/screen (input operation)
273 hline/window (\fBstdscr\fP)
274 hline_set/window (\fBstdscr\fP)
278 in_wch/window (\fBstdscr\fP)
279 in_wchnstr/window (\fBstdscr\fP)
280 in_wchstr/window (\fBstdscr\fP)
281 inch/window (\fBstdscr\fP)
282 inchnstr/window (\fBstdscr\fP)
283 inchstr/window (\fBstdscr\fP)
286 initscr/global (locks screen list)
287 innstr/window (\fBstdscr\fP)
288 innwstr/window (\fBstdscr\fP)
289 ins_nwstr/window (\fBstdscr\fP)
290 ins_wch/window (\fBstdscr\fP)
291 ins_wstr/window (\fBstdscr\fP)
292 insch/window (\fBstdscr\fP)
293 insdelln/window (\fBstdscr\fP)
294 insertln/window (\fBstdscr\fP)
295 insnstr/window (\fBstdscr\fP)
296 insstr/window (\fBstdscr\fP)
297 instr/window (\fBstdscr\fP)
299 inwstr/window (\fBstdscr\fP)
306 is_linetouched/window
311 is_term_resized/terminal
315 key_name/global (static data)
317 keyname/global (static data)
326 mouse_trafo/window (\fBstdscr\fP)
329 move/window (\fBstdscr\fP)
330 mvadd_wch/window (\fBstdscr\fP)
331 mvadd_wchnstr/window (\fBstdscr\fP)
332 mvadd_wchstr/window (\fBstdscr\fP)
333 mvaddch/window (\fBstdscr\fP)
334 mvaddchnstr/window (\fBstdscr\fP)
335 mvaddchstr/window (\fBstdscr\fP)
336 mvaddnstr/window (\fBstdscr\fP)
337 mvaddnwstr/window (\fBstdscr\fP)
338 mvaddstr/window (\fBstdscr\fP)
339 mvaddwstr/window (\fBstdscr\fP)
340 mvchgat/window (\fBstdscr\fP)
342 mvdelch/window (\fBstdscr\fP)
343 mvderwin/window (\fBstdscr\fP)
344 mvget_wch/screen (input operation)
345 mvget_wstr/screen (input operation)
346 mvgetch/screen (input operation)
347 mvgetn_wstr/screen (input operation)
348 mvgetnstr/screen (input operation)
349 mvgetstr/screen (input operation)
350 mvhline/window (\fBstdscr\fP)
351 mvhline_set/window (\fBstdscr\fP)
352 mvin_wch/window (\fBstdscr\fP)
353 mvin_wchnstr/window (\fBstdscr\fP)
354 mvin_wchstr/window (\fBstdscr\fP)
355 mvinch/window (\fBstdscr\fP)
356 mvinchnstr/window (\fBstdscr\fP)
357 mvinchstr/window (\fBstdscr\fP)
358 mvinnstr/window (\fBstdscr\fP)
359 mvinnwstr/window (\fBstdscr\fP)
360 mvins_nwstr/window (\fBstdscr\fP)
361 mvins_wch/window (\fBstdscr\fP)
362 mvins_wstr/window (\fBstdscr\fP)
363 mvinsch/window (\fBstdscr\fP)
364 mvinsnstr/window (\fBstdscr\fP)
365 mvinsstr/window (\fBstdscr\fP)
366 mvinstr/window (\fBstdscr\fP)
367 mvinwstr/window (\fBstdscr\fP)
368 mvprintw/window (\fBstdscr\fP)
370 mvvline/window (\fBstdscr\fP)
371 mvvline_set/window (\fBstdscr\fP)
373 mvwadd_wchnstr/window
384 mvwget_wch/screen (input operation)
385 mvwget_wstr/screen (input operation)
386 mvwgetch/screen (input operation)
387 mvwgetn_wstr/screen (input operation)
388 mvwgetnstr/screen (input operation)
389 mvwgetstr/screen (input operation)
414 newpad/global (locks window list)
415 newscr/screen (read-only)
416 newterm/global (locks screen list)
417 newwin/global (locks window list)
427 numcodes/global (read-only)
428 numfnames/global (read-only)
429 numnames/global (read-only)
431 overlay/window (locks source, target)
432 overwrite/window (locks source, target)
445 reset_prog_mode/screen
446 reset_shell_mode/screen
448 resize_term/screen (locks window list)
451 ripoffline/global (static data)
458 scrl/window (\fBstdscr\fP)
464 set_term/global (locks screen list, screen)
466 setscrreg/window (\fBstdscr\fP)
479 slk_noutrefresh/screen
488 \fBstdscr\fP/screen (read-only)
489 strcodes/global (read-only)
490 strfnames/global (read-only)
491 strnames/global (read-only)
506 timeout/window (\fBstdscr\fP)
509 tparm/global (static data)
511 trace/global (static data)
512 ttytype/screen (read-only)
515 unget_wch/screen (input operation)
516 ungetch/screen (input operation)
517 ungetmouse/screen (input operation)
519 use_default_colors/screen
520 use_env/global (static data)
521 use_extended_names/global (static data)
522 use_legacy_coding/screen
523 use_screen/global (locks screen list, screen)
524 use_window/global (locks window list, window)
529 vline/window (\fBstdscr\fP)
530 vline_set/window (\fBstdscr\fP)
563 wcursyncup/screen (affects window plus parents)
570 wget_wch/screen (input operation)
571 wget_wstr/screen (input operation)
573 wgetch/screen (input operation)
575 wgetn_wstr/screen (input operation)
576 wgetnstr/screen (input operation)
579 wgetstr/screen (input operation)
606 wresize/window (locks window list)
612 wsyncdown/screen (affects window plus parents)
613 wsyncup/screen (affects window plus parents)
616 wunctrl/global (static data)
620 .\" ***************************************************************************
622 \fB\%get_escdelay\fP returns the value of \fB\%ESCDELAY\fP.
623 \fB\%set_escdelay\fP and \fB\%set_tabsize\fP return \fBERR\fP upon
624 failure and \fBOK\fP upon successful completion.
625 \fB\%use_screen\fP and \fB\%use_window\fP return the \fIint\fP returned
626 by the user-supplied function they are called with.
628 \fI\%ncurses\fP provides both a C function and a preprocessor macro for
629 each function documented in this page.
631 These routines are specific to \fI\%ncurses\fP.
632 They were not supported on Version 7, BSD or System V implementations.
633 It is recommended that any code depending on \fI\%ncurses\fP extensions
634 be conditioned using \fB\%NCURSES_VERSION\fP.
637 \fB\%curs_opaque\fP(3X),
638 \fB\%curs_variables\fP(3X)