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