1 .\"***************************************************************************
2 .\" Copyright (c) 2008-2010,2012 Free Software Foundation, Inc. *
4 .\" Permission is hereby granted, free of charge, to any person obtaining a *
5 .\" copy of this software and associated documentation files (the *
6 .\" "Software"), to deal in the Software without restriction, including *
7 .\" without limitation the rights to use, copy, modify, merge, publish, *
8 .\" distribute, distribute with modifications, sublicense, and/or sell *
9 .\" copies of the Software, and to permit persons to whom the Software is *
10 .\" furnished to do so, subject to the following conditions: *
12 .\" The above copyright notice and this permission notice shall be included *
13 .\" in all copies or substantial portions of the Software. *
15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
18 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
19 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
20 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
21 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" Except as contained in this notice, the name(s) of the above copyright *
24 .\" holders shall not be used in advertising or otherwise to promote the *
25 .\" sale, use or other dealings in this Software without prior written *
27 .\"***************************************************************************
29 .\" $Id: curs_threads.3x,v 1.19 2012/05/26 17:03:26 tom Exp $
30 .TH curs_threads 3X ""
38 \fBuse_window\fR \- \fBcurses\fR thread support
42 \fB#include <curses.h>\fR
44 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR
46 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR
48 \fBint get_escdelay(void);\fR
50 \fBint set_escdelay(int size);\fR
52 \fBint set_tabsize(int size);\fR
54 \fBint use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);\fR
56 \fBint use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);\fR
59 This implementation can be configured to provide rudimentary support
60 for multi-threaded applications.
61 This makes a different set of libraries, e.g., \fIlibncursest\fP since
62 the binary interfaces are different.
64 Rather than modify the interfaces to pass a thread specifier to
65 each function, it adds a few functions which can be used in any
66 configuration which hide the mutex's needed to prevent concurrent
67 use of the global variables when configured for threading.
69 In addition to forcing access to members of the \fBWINDOW\fP structure
70 to be via functions (see \fBcurs_opaque\fP(3x)),
71 it makes functions of the common global variables,
82 Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
85 Even this is not enough to make a thread-safe application using curses.
86 A multi-threaded application would be expected to have threads updating
87 separate windows (within the same device),
88 or updating on separate screens (on different devices).
89 Also, a few of the global variables are considered writable by some
91 The functions described here address these special situations.
93 The ESCDELAY and TABSIZE global variables are modified by some applications.
94 To modify them in any configuration,
95 use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
96 Other global variables are not modifiable.
98 The \fBget_escdelay\fP function returns the value for ESCDELAY.
100 The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
101 granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
102 parameters, and call a user-supplied function,
103 passing it a \fIdata\fP parameter,
104 and returning the value from the user-supplied function to the application.
105 .\" ***************************************************************************
107 All of the ncurses library functions assume that the locale is not
108 altered during operation.
110 they use data which is maintained within a hierarchy of scopes.
113 global data, e.g., used in the low-level terminfo or termcap interfaces.
115 terminal data, e.g., associated with a call to \fIset_curterm\fP.
116 The terminal data are initialized when screens are created.
118 screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP.
120 window data, e.g., associated with a call to \fInewwin\fP or \fIsubwin\fP.
121 Windows are associated with screens.
122 Pads are not necessarily associated with a particular screen.
124 Most curses applications operate on one or more windows within a single screen.
126 reentrant, i.e., it uses only the data passed as parameters.
129 This table lists the scope of data used for each symbol in the
130 ncurses library when it is configured to support threading:
138 COLORS/screen (readonly)
140 COLOR_PAIRS/screen (readonly)
141 COLS/screen (readonly)
142 ESCDELAY/screen (readonly, see \fIset_escdelay\fP)
143 LINES/screen (readonly)
144 PAIR_NUMBER/reentrant
147 TABSIZE/screen (readonly)
149 acs_map/screen (readonly)
150 add_wch/window (stdscr)
151 add_wchnstr/window (stdscr)
152 add_wchstr/window (stdscr)
153 addch/window (stdscr)
154 addchnstr/window (stdscr)
155 addchstr/window (stdscr)
156 addnstr/window (stdscr)
157 addnwstr/window (stdscr)
158 addstr/window (stdscr)
159 addwstr/window (stdscr)
160 assume_default_colors/screen
161 attr_get/window (stdscr)
162 attr_off/window (stdscr)
163 attr_on/window (stdscr)
164 attr_set/window (stdscr)
165 attroff/window (stdscr)
166 attron/window (stdscr)
167 attrset/window (stdscr)
171 bkgdset/window (stdscr)
172 bkgrnd/window (stdscr)
173 bkgrndset/window (stdscr)
174 boolcodes/global (readonly)
175 boolfnames/global (readonly)
176 boolnames/global (readonly)
177 border/window (stdscr)
178 border_set/window (stdscr)
180 box_set/window (stdscr)
181 can_change_color/terminal
183 chgat/window (stdscr)
184 clear/window (stdscr)
186 clrtobot/window (stdscr)
187 clrtoeol/window (stdscr)
189 color_set/window (stdscr)
190 copywin/window locks(source, target)
193 curscr/screen (readonly)
194 curses_version/global (readonly)
195 def_prog_mode/terminal
196 def_shell_mode/terminal
200 delch/window (stdscr)
201 deleteln/window (stdscr)
202 delscreen/global locks(screenlist, screen)
203 delwin/global locks(windowlist)
206 dupwin/screen locks(window)
208 echo_wchar/window (stdscr)
209 echochar/window (stdscr)
211 erase/window (stdscr)
212 erasechar/window (stdscr)
213 erasewchar/window (stdscr)
217 get_wch/screen (input-operation)
218 get_wstr/screen (input-operation)
225 getch/screen (input-operation)
230 getmouse/screen (input-operation)
231 getn_wstr/screen (input-operation)
232 getnstr/screen (input-operation)
235 getstr/screen (input-operation)
236 getwin/screen (input-operation)
242 hline/window (stdscr)
243 hline_set/window (stdscr)
247 in_wch/window (stdscr)
248 in_wchnstr/window (stdscr)
249 in_wchstr/window (stdscr)
251 inchnstr/window (stdscr)
252 inchstr/window (stdscr)
255 initscr/global locks(screenlist)
256 innstr/window (stdscr)
257 innwstr/window (stdscr)
258 ins_nwstr/window (stdscr)
259 ins_wch/window (stdscr)
260 ins_wstr/window (stdscr)
261 insch/window (stdscr)
262 insdelln/window (stdscr)
263 insertln/window (stdscr)
264 insnstr/window (stdscr)
265 insstr/window (stdscr)
266 instr/window (stdscr)
268 inwstr/window (stdscr)
275 is_linetouched/window
280 is_term_resized/terminal
284 key_name/global (static data)
286 keyname/global (static data)
295 mouse_trafo/window (stdscr)
299 mvadd_wch/window (stdscr)
300 mvadd_wchnstr/window (stdscr)
301 mvadd_wchstr/window (stdscr)
302 mvaddch/window (stdscr)
303 mvaddchnstr/window (stdscr)
304 mvaddchstr/window (stdscr)
305 mvaddnstr/window (stdscr)
306 mvaddnwstr/window (stdscr)
307 mvaddstr/window (stdscr)
308 mvaddwstr/window (stdscr)
309 mvchgat/window (stdscr)
311 mvdelch/window (stdscr)
312 mvderwin/window (stdscr)
313 mvget_wch/screen (input-operation)
314 mvget_wstr/screen (input-operation)
315 mvgetch/screen (input-operation)
316 mvgetn_wstr/screen (input-operation)
317 mvgetnstr/screen (input-operation)
318 mvgetstr/screen (input-operation)
319 mvhline/window (stdscr)
320 mvhline_set/window (stdscr)
321 mvin_wch/window (stdscr)
322 mvin_wchnstr/window (stdscr)
323 mvin_wchstr/window (stdscr)
324 mvinch/window (stdscr)
325 mvinchnstr/window (stdscr)
326 mvinchstr/window (stdscr)
327 mvinnstr/window (stdscr)
328 mvinnwstr/window (stdscr)
329 mvins_nwstr/window (stdscr)
330 mvins_wch/window (stdscr)
331 mvins_wstr/window (stdscr)
332 mvinsch/window (stdscr)
333 mvinsnstr/window (stdscr)
334 mvinsstr/window (stdscr)
335 mvinstr/window (stdscr)
336 mvinwstr/window (stdscr)
337 mvprintw/window (stdscr)
339 mvvline/window (stdscr)
340 mvvline_set/window (stdscr)
342 mvwadd_wchnstr/window
353 mvwget_wch/screen (input-operation)
354 mvwget_wstr/screen (input-operation)
355 mvwgetch/screen (input-operation)
356 mvwgetn_wstr/screen (input-operation)
357 mvwgetnstr/screen (input-operation)
358 mvwgetstr/screen (input-operation)
383 newpad/global locks(windowlist)
384 newscr/screen (readonly)
385 newterm/global locks(screenlist)
386 newwin/global locks(windowlist)
396 numcodes/global (readonly)
397 numfnames/global (readonly)
398 numnames/global (readonly)
400 overlay/window locks(source, target)
401 overwrite/window locks(source, target)
414 reset_prog_mode/screen
415 reset_shell_mode/screen
417 resize_term/screen locks(windowlist)
420 ripoffline/global (static data)
433 set_term/global locks(screenlist, screen)
435 setscrreg/window (stdscr)
448 slk_noutrefresh/screen
457 stdscr/screen (readonly)
458 strcodes/global (readonly)
459 strfnames/global (readonly)
460 strnames/global (readonly)
475 timeout/window (stdscr)
478 tparm/global (static data)
480 trace/global (static data)
481 ttytype/screen (readonly)
484 unget_wch/screen (input-operation)
485 ungetch/screen (input-operation)
486 ungetmouse/screen (input-operation)
488 use_default_colors/screen
489 use_env/global (static data)
490 use_extended_names/global (static data)
491 use_legacy_coding/screen
492 use_screen/global locks(screenlist, screen)
493 use_window/global locks(windowlist, window)
498 vline/window (stdscr)
499 vline_set/window (stdscr)
532 wcursyncup/screen (affects window plus parents)
539 wget_wch/screen (input-operation)
540 wget_wstr/screen (input-operation)
542 wgetch/screen (input-operation)
543 wgetn_wstr/screen (input-operation)
544 wgetnstr/screen (input-operation)
547 wgetstr/screen (input-operation)
574 wresize/window locks(windowlist)
580 wsyncdown/screen (affects window plus parents)
581 wsyncup/screen (affects window plus parents)
584 wunctrl/global (static data)
588 .\" ***************************************************************************
590 These functions all return TRUE or FALSE, except as noted.
592 Both a macro and a function are provided for each name.
594 These routines are specific to ncurses.
595 They were not supported on Version 7, BSD or System V implementations.
596 It is recommended that any code depending on ncurses extensions
597 be conditioned using NCURSES_VERSION.
600 \fBcurs_opaque\fR(3X),
601 \fBcurs_variables\fR(3X).