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.47 2023/10/07 21:19:07 tom Exp $
32 .TH curs_threads 3X 2023-10-07 "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 \fIncurses\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 \fIncurses\fP's application binary interface
81 Instead of modifying the programming interface (API) to make
82 \fIncurses\fP functions expect an additional argument specifying a
84 the library adds a few 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 \fIncurses\fP threading support requires the use of functions to access
92 members of the \fI\%WINDOW\fP structure (see \fBcurs_opaque\fP(3X)).
93 It further makes functions of the common global variables
104 maintaining them as as read-only values in the \fISCREEN\fP structure.
106 Even this is not enough to make an application using \fIcurses\fP
108 We would expect a multi-threaded application to have threads updating
109 separate windows (on the same device),
110 and separate screens (on different devices).
112 applications expect a few of the global variables to be writable.
113 The functions described here address these special situations.
115 The \fB\%ESCDELAY\fP and \fB\%TABSIZE\fP global variables are modified
116 by some applications.
117 To modify them in any configuration,
118 use the \fB\%set_escdelay\fP or \fB\%set_tabsize\fP functions.
119 Other global variables are not modifiable.
120 \fBget_escdelay\fP retrieves \fB\%ESCDELAY\fP's value.
122 The \fBuse_window\fP and \fBuse_screen\fP functions provide
123 coarse-grained mutexes for their respective \fI\%WINDOW\fP and
124 \fI\%SCREEN\fP parameters;
125 they call a user-supplied function,
126 pass it a \fIdata\fP parameter,
127 and return the value from the user-supplied function to the application.
128 .\" ***************************************************************************
130 All \fIncurses\fP library functions assume that the locale is not
131 altered during operation.
133 they use data that is maintained within a hierarchy of scopes.
135 global data used in the low-level \fIterminfo\fP or \fItermcap\fP
138 terminal data associated with a call to \fBset_curterm\fP(3X)
140 Terminal data are initialized when screens are created.
142 screen data associated with a call to \fBnewterm\fP(3X) or
145 window data associated with a call to \fBnewwin\fP(3X) or
148 Windows are associated with screens.
149 Pads are not necessarily associated with any particular screen.
151 Most \fIcurses\fP applications operate on one or more windows within a
154 reentrant data associated with \*(``pure\*('' functions that alter no
157 The following table lists the scope of each symbol in the \fIncurses\fP
158 library when configured to support multi-threaded applications.
167 COLORS/screen (read-only)
169 COLOR_PAIRS/screen (read-only)
170 COLS/screen (read-only)
171 ESCDELAY/screen (read-only; see \fBset_escdelay\fP)
172 LINES/screen (read-only)
173 PAIR_NUMBER/reentrant
176 TABSIZE/screen (read-only; see \fBset_tabsize\fP)
178 acs_map/screen (read-only)
179 add_wch/window (\fBstdscr\fP)
180 add_wchnstr/window (\fBstdscr\fP)
181 add_wchstr/window (\fBstdscr\fP)
182 addch/window (\fBstdscr\fP)
183 addchnstr/window (\fBstdscr\fP)
184 addchstr/window (\fBstdscr\fP)
185 addnstr/window (\fBstdscr\fP)
186 addnwstr/window (\fBstdscr\fP)
187 addstr/window (\fBstdscr\fP)
188 addwstr/window (\fBstdscr\fP)
189 assume_default_colors/screen
190 attr_get/window (\fBstdscr\fP)
191 attr_off/window (\fBstdscr\fP)
192 attr_on/window (\fBstdscr\fP)
193 attr_set/window (\fBstdscr\fP)
194 attroff/window (\fBstdscr\fP)
195 attron/window (\fBstdscr\fP)
196 attrset/window (\fBstdscr\fP)
199 bkgd/window (\fBstdscr\fP)
200 bkgdset/window (\fBstdscr\fP)
201 bkgrnd/window (\fBstdscr\fP)
202 bkgrndset/window (\fBstdscr\fP)
203 boolcodes/global (read-only)
204 boolfnames/global (read-only)
205 boolnames/global (read-only)
206 border/window (\fBstdscr\fP)
207 border_set/window (\fBstdscr\fP)
208 box/window (\fBstdscr\fP)
209 box_set/window (\fBstdscr\fP)
210 can_change_color/terminal
212 chgat/window (\fBstdscr\fP)
213 clear/window (\fBstdscr\fP)
215 clrtobot/window (\fBstdscr\fP)
216 clrtoeol/window (\fBstdscr\fP)
218 color_set/window (\fBstdscr\fP)
219 copywin/window (locks source, target)
222 curscr/screen (read-only)
223 curses_version/global (read-only)
224 def_prog_mode/terminal
225 def_shell_mode/terminal
229 delch/window (\fBstdscr\fP)
230 deleteln/window (\fBstdscr\fP)
231 delscreen/global (locks screen list, screen)
232 delwin/global (locks window list)
235 dupwin/screen (locks window)
237 echo_wchar/window (\fBstdscr\fP)
238 echochar/window (\fBstdscr\fP)
240 erase/window (\fBstdscr\fP)
241 erasechar/window (\fBstdscr\fP)
242 erasewchar/window (\fBstdscr\fP)
246 get_wch/screen (input operation)
247 get_wstr/screen (input operation)
254 getch/screen (input operation)
259 getmouse/screen (input operation)
260 getn_wstr/screen (input operation)
261 getnstr/screen (input operation)
264 getstr/screen (input operation)
265 getwin/screen (input operation)
271 hline/window (\fBstdscr\fP)
272 hline_set/window (\fBstdscr\fP)
276 in_wch/window (\fBstdscr\fP)
277 in_wchnstr/window (\fBstdscr\fP)
278 in_wchstr/window (\fBstdscr\fP)
279 inch/window (\fBstdscr\fP)
280 inchnstr/window (\fBstdscr\fP)
281 inchstr/window (\fBstdscr\fP)
284 initscr/global (locks screen list)
285 innstr/window (\fBstdscr\fP)
286 innwstr/window (\fBstdscr\fP)
287 ins_nwstr/window (\fBstdscr\fP)
288 ins_wch/window (\fBstdscr\fP)
289 ins_wstr/window (\fBstdscr\fP)
290 insch/window (\fBstdscr\fP)
291 insdelln/window (\fBstdscr\fP)
292 insertln/window (\fBstdscr\fP)
293 insnstr/window (\fBstdscr\fP)
294 insstr/window (\fBstdscr\fP)
295 instr/window (\fBstdscr\fP)
297 inwstr/window (\fBstdscr\fP)
304 is_linetouched/window
309 is_term_resized/terminal
313 key_name/global (static data)
315 keyname/global (static data)
324 mouse_trafo/window (\fBstdscr\fP)
327 move/window (\fBstdscr\fP)
328 mvadd_wch/window (\fBstdscr\fP)
329 mvadd_wchnstr/window (\fBstdscr\fP)
330 mvadd_wchstr/window (\fBstdscr\fP)
331 mvaddch/window (\fBstdscr\fP)
332 mvaddchnstr/window (\fBstdscr\fP)
333 mvaddchstr/window (\fBstdscr\fP)
334 mvaddnstr/window (\fBstdscr\fP)
335 mvaddnwstr/window (\fBstdscr\fP)
336 mvaddstr/window (\fBstdscr\fP)
337 mvaddwstr/window (\fBstdscr\fP)
338 mvchgat/window (\fBstdscr\fP)
340 mvdelch/window (\fBstdscr\fP)
341 mvderwin/window (\fBstdscr\fP)
342 mvget_wch/screen (input operation)
343 mvget_wstr/screen (input operation)
344 mvgetch/screen (input operation)
345 mvgetn_wstr/screen (input operation)
346 mvgetnstr/screen (input operation)
347 mvgetstr/screen (input operation)
348 mvhline/window (\fBstdscr\fP)
349 mvhline_set/window (\fBstdscr\fP)
350 mvin_wch/window (\fBstdscr\fP)
351 mvin_wchnstr/window (\fBstdscr\fP)
352 mvin_wchstr/window (\fBstdscr\fP)
353 mvinch/window (\fBstdscr\fP)
354 mvinchnstr/window (\fBstdscr\fP)
355 mvinchstr/window (\fBstdscr\fP)
356 mvinnstr/window (\fBstdscr\fP)
357 mvinnwstr/window (\fBstdscr\fP)
358 mvins_nwstr/window (\fBstdscr\fP)
359 mvins_wch/window (\fBstdscr\fP)
360 mvins_wstr/window (\fBstdscr\fP)
361 mvinsch/window (\fBstdscr\fP)
362 mvinsnstr/window (\fBstdscr\fP)
363 mvinsstr/window (\fBstdscr\fP)
364 mvinstr/window (\fBstdscr\fP)
365 mvinwstr/window (\fBstdscr\fP)
366 mvprintw/window (\fBstdscr\fP)
368 mvvline/window (\fBstdscr\fP)
369 mvvline_set/window (\fBstdscr\fP)
371 mvwadd_wchnstr/window
382 mvwget_wch/screen (input operation)
383 mvwget_wstr/screen (input operation)
384 mvwgetch/screen (input operation)
385 mvwgetn_wstr/screen (input operation)
386 mvwgetnstr/screen (input operation)
387 mvwgetstr/screen (input operation)
412 newpad/global (locks window list)
413 newscr/screen (read-only)
414 newterm/global (locks screen list)
415 newwin/global (locks window list)
425 numcodes/global (read-only)
426 numfnames/global (read-only)
427 numnames/global (read-only)
429 overlay/window (locks source, target)
430 overwrite/window (locks source, target)
443 reset_prog_mode/screen
444 reset_shell_mode/screen
446 resize_term/screen (locks window list)
449 ripoffline/global (static data)
456 scrl/window (\fBstdscr\fP)
462 set_term/global (locks screen list, screen)
464 setscrreg/window (\fBstdscr\fP)
477 slk_noutrefresh/screen
486 \fBstdscr\fP/screen (read-only)
487 strcodes/global (read-only)
488 strfnames/global (read-only)
489 strnames/global (read-only)
504 timeout/window (\fBstdscr\fP)
507 tparm/global (static data)
509 trace/global (static data)
510 ttytype/screen (read-only)
513 unget_wch/screen (input operation)
514 ungetch/screen (input operation)
515 ungetmouse/screen (input operation)
517 use_default_colors/screen
518 use_env/global (static data)
519 use_extended_names/global (static data)
520 use_legacy_coding/screen
521 use_screen/global (locks screen list, screen)
522 use_window/global (locks window list, window)
527 vline/window (\fBstdscr\fP)
528 vline_set/window (\fBstdscr\fP)
561 wcursyncup/screen (affects window plus parents)
568 wget_wch/screen (input operation)
569 wget_wstr/screen (input operation)
571 wgetch/screen (input operation)
573 wgetn_wstr/screen (input operation)
574 wgetnstr/screen (input operation)
577 wgetstr/screen (input operation)
604 wresize/window (locks window list)
610 wsyncdown/screen (affects window plus parents)
611 wsyncup/screen (affects window plus parents)
614 wunctrl/global (static data)
618 .\" ***************************************************************************
620 \fB\%get_escdelay\fP returns the value of \fB\%ESCDELAY\fP.
621 \fB\%set_escdelay\fP and \fB\%set_tabsize\fP return \fBERR\fP upon
622 failure and \fBOK\fP upon successful completion.
623 \fB\%use_screen\fP and \fB\%use_window\fP return the \fIint\fP returned
624 by the user-supplied function they are called with.
626 \fIncurses\fP provides both a C function and a preprocessor macro for
627 each function documented in this page.
629 These routines are specific to \fIncurses\fP.
630 They were not supported on Version 7, BSD or System V implementations.
631 It is recommended that any code depending on \fIncurses\fP extensions
632 be conditioned using \fB\%NCURSES_VERSION\fP.
635 \fB\%curs_opaque\fP(3X),
636 \fB\%curs_variables\fP(3X)