ncurses 6.2 - patch 20201205
[ncurses.git] / man / curs_threads.3x
1 .\"***************************************************************************
2 .\" Copyright 2020 Thomas E. Dickey                                          *
3 .\" Copyright 2008-2015,2017 Free Software Foundation, Inc.                  *
4 .\"                                                                          *
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:                 *
12 .\"                                                                          *
13 .\" The above copyright notice and this permission notice shall be included  *
14 .\" in all copies or substantial portions of the Software.                   *
15 .\"                                                                          *
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.                               *
23 .\"                                                                          *
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       *
27 .\" authorization.                                                           *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_threads.3x,v 1.26 2020/10/24 09:47:37 tom Exp $
31 .TH curs_threads 3X ""
32 .de bP
33 .ie n  .IP \(bu 4
34 .el    .IP \(bu 2
35 ..
36 .na
37 .hy 0
38 .SH NAME
39 \fBcurs_threads\fR \- \fBcurses\fR thread support
40 .ad
41 .hy
42 .SH SYNOPSIS
43 \fB#include <curses.h>\fR
44 .sp
45 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR
46 .br
47 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR
48 .sp
49 \fBint get_escdelay(void);\fR
50 .br
51 \fBint set_escdelay(int \fP\fIsize\fP\fB);\fR
52 .br
53 \fBint set_tabsize(int \fP\fIsize\fP\fB);\fR
54 .sp
55 \fBint use_screen(SCREEN *\fP\fIscr\fP\fB, NCURSES_SCREEN_CB \fP\fIfunc\fP\fB, void *\fP\fIdata\fP\fB);\fR
56 .br
57 \fBint use_window(WINDOW *\fP\fIwin\fP\fB, NCURSES_WINDOW_CB \fP\fIfunc\fP\fB, void *\fP\fIdata\fP\fB);\fR
58 .br
59 .SH DESCRIPTION
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., \fIlibncursest\fP since
63 the binary interfaces are different.
64 .PP
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.
69 .PP
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,
73 e.g.,
74 COLORS,
75 COLOR_PAIRS,
76 COLS,
77 ESCDELAY,
78 LINES,
79 TABSIZE
80 curscr,
81 newscr and
82 ttytype.
83 Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
84 structure.
85 .PP
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
91 applications.
92 The functions described here address these special situations.
93 .PP
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.
98 .PP
99 The \fBget_escdelay\fP function returns the value for ESCDELAY.
100 .PP
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 .\" ***************************************************************************
107 .SS USAGE
108 All of the ncurses library functions assume that the locale is not
109 altered during operation.
110 In addition,
111 they use data which is maintained within a hierarchy of scopes.
112 .RS 3
113 .bP
114 global data, e.g., used in the low-level terminfo or termcap interfaces.
115 .bP
116 terminal data, e.g., associated with a call to \fIset_curterm\fP.
117 The terminal data are initialized when screens are created.
118 .bP
119 screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP.
120 .bP
121 window data, e.g., associated with a call to \fInewwin\fP or \fIsubwin\fP.
122 Windows are associated with screens.
123 Pads are not necessarily associated with a particular screen.
124 .IP
125 Most curses applications operate on one or more windows within a single screen.
126 .bP
127 reentrant, i.e., it uses only the data passed as parameters.
128 .RE
129 .PP
130 This table lists the scope of data used for each symbol in the
131 ncurses library when it is configured to support threading:
132 .TS
133 center tab(/);
134 l l
135 l l .
136 Symbol/Scope
137 =
138 BC/global
139 COLORS/screen (readonly)
140 COLOR_PAIR/reentrant
141 COLOR_PAIRS/screen (readonly)
142 COLS/screen (readonly)
143 ESCDELAY/screen (readonly, see \fIset_escdelay\fP)
144 LINES/screen (readonly)
145 PAIR_NUMBER/reentrant
146 PC/global
147 SP/global
148 TABSIZE/screen (readonly)
149 UP/global
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)
169 baudrate/screen
170 beep/screen
171 bkgd/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)
180 box/window (stdscr)
181 box_set/window (stdscr)
182 can_change_color/terminal
183 cbreak/screen
184 chgat/window (stdscr)
185 clear/window (stdscr)
186 clearok/window
187 clrtobot/window (stdscr)
188 clrtoeol/window (stdscr)
189 color_content/screen
190 color_set/window (stdscr)
191 copywin/window locks(source, target)
192 cur_term/terminal
193 curs_set/screen
194 curscr/screen (readonly)
195 curses_version/global (readonly)
196 def_prog_mode/terminal
197 def_shell_mode/terminal
198 define_key/screen
199 del_curterm/screen
200 delay_output/screen
201 delch/window (stdscr)
202 deleteln/window (stdscr)
203 delscreen/global locks(screenlist, screen)
204 delwin/global locks(windowlist)
205 derwin/screen
206 doupdate/screen
207 dupwin/screen locks(window)
208 echo/screen
209 echo_wchar/window (stdscr)
210 echochar/window (stdscr)
211 endwin/screen
212 erase/window (stdscr)
213 erasechar/window (stdscr)
214 erasewchar/window (stdscr)
215 filter/global
216 flash/terminal
217 flushinp/screen
218 get_wch/screen (input-operation)
219 get_wstr/screen (input-operation)
220 getattrs/window
221 getbegx/window
222 getbegy/window
223 getbkgd/window
224 getbkgrnd/window
225 getcchar/reentrant
226 getch/screen (input-operation)
227 getcurx/window
228 getcury/window
229 getmaxx/window
230 getmaxy/window
231 getmouse/screen (input-operation)
232 getn_wstr/screen (input-operation)
233 getnstr/screen (input-operation)
234 getparx/window
235 getpary/window
236 getstr/screen (input-operation)
237 getwin/screen (input-operation)
238 halfdelay/screen
239 has_colors/terminal
240 has_ic/terminal
241 has_il/terminal
242 has_key/screen
243 hline/window (stdscr)
244 hline_set/window (stdscr)
245 idcok/window
246 idlok/window
247 immedok/window
248 in_wch/window (stdscr)
249 in_wchnstr/window (stdscr)
250 in_wchstr/window (stdscr)
251 inch/window (stdscr)
252 inchnstr/window (stdscr)
253 inchstr/window (stdscr)
254 init_color/screen
255 init_pair/screen
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)
268 intrflush/terminal
269 inwstr/window (stdscr)
270 is_cleared/window
271 is_idcok/window
272 is_idlok/window
273 is_immedok/window
274 is_keypad/window
275 is_leaveok/window
276 is_linetouched/window
277 is_nodelay/window
278 is_notimeout/window
279 is_scrollok/window
280 is_syncok/window
281 is_term_resized/terminal
282 is_wintouched/window
283 isendwin/screen
284 key_defined/screen
285 key_name/global (static data)
286 keybound/screen
287 keyname/global (static data)
288 keyok/screen
289 keypad/window
290 killchar/terminal
291 killwchar/terminal
292 leaveok/window
293 longname/screen
294 mcprint/terminal
295 meta/screen
296 mouse_trafo/window (stdscr)
297 mouseinterval/screen
298 mousemask/screen
299 move/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)
311 mvcur/screen
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)
339 mvscanw/screen
340 mvvline/window (stdscr)
341 mvvline_set/window (stdscr)
342 mvwadd_wch/window
343 mvwadd_wchnstr/window
344 mvwadd_wchstr/window
345 mvwaddch/window
346 mvwaddchnstr/window
347 mvwaddchstr/window
348 mvwaddnstr/window
349 mvwaddnwstr/window
350 mvwaddstr/window
351 mvwaddwstr/window
352 mvwchgat/window
353 mvwdelch/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)
360 mvwhline/window
361 mvwhline_set/window
362 mvwin/window
363 mvwin_wch/window
364 mvwin_wchnstr/window
365 mvwin_wchstr/window
366 mvwinch/window
367 mvwinchnstr/window
368 mvwinchstr/window
369 mvwinnstr/window
370 mvwinnwstr/window
371 mvwins_nwstr/window
372 mvwins_wch/window
373 mvwins_wstr/window
374 mvwinsch/window
375 mvwinsnstr/window
376 mvwinsstr/window
377 mvwinstr/window
378 mvwinwstr/window
379 mvwprintw/window
380 mvwscanw/screen
381 mvwvline/window
382 mvwvline_set/window
383 napms/reentrant
384 newpad/global locks(windowlist)
385 newscr/screen (readonly)
386 newterm/global locks(screenlist)
387 newwin/global locks(windowlist)
388 nl/screen
389 nocbreak/screen
390 nodelay/window
391 noecho/screen
392 nofilter/global
393 nonl/screen
394 noqiflush/terminal
395 noraw/screen
396 notimeout/window
397 numcodes/global (readonly)
398 numfnames/global (readonly)
399 numnames/global (readonly)
400 ospeed/global
401 overlay/window locks(source, target)
402 overwrite/window locks(source, target)
403 pair_content/screen
404 pecho_wchar/screen
405 pechochar/screen
406 pnoutrefresh/screen
407 prefresh/screen
408 printw/window
409 putp/global
410 putwin/window
411 qiflush/terminal
412 raw/screen
413 redrawwin/window
414 refresh/screen
415 reset_prog_mode/screen
416 reset_shell_mode/screen
417 resetty/terminal
418 resize_term/screen locks(windowlist)
419 resizeterm/screen
420 restartterm/screen
421 ripoffline/global (static data)
422 savetty/terminal
423 scanw/screen
424 scr_dump/screen
425 scr_init/screen
426 scr_restore/screen
427 scr_set/screen
428 scrl/window (stdscr)
429 scroll/window
430 scrollok/window
431 set_curterm/screen
432 set_escdelay/screen
433 set_tabsize/screen
434 set_term/global locks(screenlist, screen)
435 setcchar/reentrant
436 setscrreg/window (stdscr)
437 setupterm/global
438 slk_attr/screen
439 slk_attr_off/screen
440 slk_attr_on/screen
441 slk_attr_set/screen
442 slk_attroff/screen
443 slk_attron/screen
444 slk_attrset/screen
445 slk_clear/screen
446 slk_color/screen
447 slk_init/screen
448 slk_label/screen
449 slk_noutrefresh/screen
450 slk_refresh/screen
451 slk_restore/screen
452 slk_set/screen
453 slk_touch/screen
454 slk_wset/screen
455 standend/window
456 standout/window
457 start_color/screen
458 stdscr/screen (readonly)
459 strcodes/global (readonly)
460 strfnames/global (readonly)
461 strnames/global (readonly)
462 subpad/window
463 subwin/window
464 syncok/window
465 term_attrs/screen
466 termattrs/screen
467 termname/terminal
468 tgetent/global
469 tgetflag/global
470 tgetnum/global
471 tgetstr/global
472 tgoto/global
473 tigetflag/terminal
474 tigetnum/terminal
475 tigetstr/terminal
476 timeout/window (stdscr)
477 touchline/window
478 touchwin/window
479 tparm/global (static data)
480 tputs/screen
481 trace/global (static data)
482 ttytype/screen (readonly)
483 typeahead/screen
484 unctrl/screen
485 unget_wch/screen (input-operation)
486 ungetch/screen (input-operation)
487 ungetmouse/screen (input-operation)
488 untouchwin/window
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)
495 vid_attr/screen
496 vid_puts/screen
497 vidattr/screen
498 vidputs/screen
499 vline/window (stdscr)
500 vline_set/window (stdscr)
501 vw_printw/window
502 vw_scanw/screen
503 vwprintw/window
504 vwscanw/screen
505 wadd_wch/window
506 wadd_wchnstr/window
507 wadd_wchstr/window
508 waddch/window
509 waddchnstr/window
510 waddchstr/window
511 waddnstr/window
512 waddnwstr/window
513 waddstr/window
514 waddwstr/window
515 wattr_get/window
516 wattr_off/window
517 wattr_on/window
518 wattr_set/window
519 wattroff/window
520 wattron/window
521 wattrset/window
522 wbkgd/window
523 wbkgdset/window
524 wbkgrnd/window
525 wbkgrndset/window
526 wborder/window
527 wborder_set/window
528 wchgat/window
529 wclear/window
530 wclrtobot/window
531 wclrtoeol/window
532 wcolor_set/window
533 wcursyncup/screen (affects window plus parents)
534 wdelch/window
535 wdeleteln/window
536 wecho_wchar/window
537 wechochar/window
538 wenclose/window
539 werase/window
540 wget_wch/screen (input-operation)
541 wget_wstr/screen (input-operation)
542 wgetbkgrnd/window
543 wgetch/screen (input-operation)
544 wgetdelay/window
545 wgetn_wstr/screen (input-operation)
546 wgetnstr/screen (input-operation)
547 wgetparent/window
548 wgetscrreg/window
549 wgetstr/screen (input-operation)
550 whline/window
551 whline_set/window
552 win_wch/window
553 win_wchnstr/window
554 win_wchstr/window
555 winch/window
556 winchnstr/window
557 winchstr/window
558 winnstr/window
559 winnwstr/window
560 wins_nwstr/window
561 wins_wch/window
562 wins_wstr/window
563 winsch/window
564 winsdelln/window
565 winsertln/window
566 winsnstr/window
567 winsstr/window
568 winstr/window
569 winwstr/window
570 wmouse_trafo/window
571 wmove/window
572 wnoutrefresh/screen
573 wprintw/window
574 wredrawln/window
575 wrefresh/screen
576 wresize/window locks(windowlist)
577 wscanw/screen
578 wscrl/window
579 wsetscrreg/window
580 wstandend/window
581 wstandout/window
582 wsyncdown/screen (affects window plus parents)
583 wsyncup/screen (affects window plus parents)
584 wtimeout/window
585 wtouchln/window
586 wunctrl/global (static data)
587 wvline/window
588 wvline_set/window
589 .TE
590 .\" ***************************************************************************
591 .SH RETURN VALUE
592 These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
593 .SH NOTES
594 Both a macro and a function are provided for each name.
595 .SH PORTABILITY
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.
600 .SH SEE ALSO
601 \fBcurses\fR(3X),
602 \fBcurs_opaque\fR(3X),
603 \fBcurs_variables\fR(3X).