| blob | 350d5eea2523ed9210c15af9f1a61ad8456f46d4 |
1 .\"***************************************************************************
2 .\" Copyright (c) 2008-2014,2015 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.23 2015/12/05 18:47:04 tom Exp $
30 .TH curs_threads 3X ""
31 .de bP
32 .IP \(bu 4
33 ..
34 .na
35 .hy 0
36 .SH NAME
37 \fBcurs_threads\fR \- \fBcurses\fR thread support
38 .ad
39 .hy
40 .SH SYNOPSIS
41 \fB#include <curses.h>\fR
42 .sp
43 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR
44 .br
45 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR
46 .br
47 \fBint get_escdelay(void);\fR
48 .br
49 \fBint set_escdelay(int size);\fR
50 .br
51 \fBint set_tabsize(int size);\fR
52 .br
53 \fBint use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);\fR
54 .br
55 \fBint use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);\fR
56 .br
57 .SH DESCRIPTION
58 This implementation can be configured to provide rudimentary support
59 for multi-threaded applications.
60 This makes a different set of libraries, e.g., \fIlibncursest\fP since
61 the binary interfaces are different.
62 .PP
63 Rather than modify the interfaces to pass a thread specifier to
64 each function, it adds a few functions which can be used in any
65 configuration which hide the mutex's needed to prevent concurrent
66 use of the global variables when configured for threading.
67 .PP
68 In addition to forcing access to members of the \fBWINDOW\fP structure
69 to be via functions (see \fBcurs_opaque\fP(3X)),
70 it makes functions of the common global variables,
71 e.g.,
72 COLORS,
73 COLOR_PAIRS,
74 COLS,
75 ESCDELAY,
76 LINES,
77 TABSIZE
78 curscr,
79 newscr and
80 ttytype.
81 Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
82 structure.
83 .PP
84 Even this is not enough to make a thread-safe application using curses.
85 A multi-threaded application would be expected to have threads updating
86 separate windows (within the same device),
87 or updating on separate screens (on different devices).
88 Also, a few of the global variables are considered writable by some
89 applications.
90 The functions described here address these special situations.
91 .PP
92 The ESCDELAY and TABSIZE global variables are modified by some applications.
93 To modify them in any configuration,
94 use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
95 Other global variables are not modifiable.
96 .PP
97 The \fBget_escdelay\fP function returns the value for ESCDELAY.
98 .PP
99 The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
100 granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
101 parameters, and call a user-supplied function,
102 passing it a \fIdata\fP parameter,
103 and returning the value from the user-supplied function to the application.
104 .\" ***************************************************************************
105 .SS USAGE
106 All of the ncurses library functions assume that the locale is not
107 altered during operation.
108 In addition,
109 they use data which is maintained within a hierarchy of scopes.
110 .RS 3
111 .bP
112 global data, e.g., used in the low-level terminfo or termcap interfaces.
113 .bP
114 terminal data, e.g., associated with a call to \fIset_curterm\fP.
115 The terminal data are initialized when screens are created.
116 .bP
117 screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP.
118 .bP
119 window data, e.g., associated with a call to \fInewwin\fP or \fIsubwin\fP.
120 Windows are associated with screens.
121 Pads are not necessarily associated with a particular screen.
122 .IP
123 Most curses applications operate on one or more windows within a single screen.
124 .bP
125 reentrant, i.e., it uses only the data passed as parameters.
126 .RE
127 .PP
128 This table lists the scope of data used for each symbol in the
129 ncurses library when it is configured to support threading:
130 .TS
131 center tab(/);
132 l l
133 l l .
134 Symbol/Scope
135 =
136 BC/global
137 COLORS/screen (readonly)
138 COLOR_PAIR/reentrant
139 COLOR_PAIRS/screen (readonly)
140 COLS/screen (readonly)
141 ESCDELAY/screen (readonly, see \fIset_escdelay\fP)
142 LINES/screen (readonly)
143 PAIR_NUMBER/reentrant
144 PC/global
145 SP/global
146 TABSIZE/screen (readonly)
147 UP/global
148 acs_map/screen (readonly)
149 add_wch/window (stdscr)
150 add_wchnstr/window (stdscr)
151 add_wchstr/window (stdscr)
152 addch/window (stdscr)
153 addchnstr/window (stdscr)
154 addchstr/window (stdscr)
155 addnstr/window (stdscr)
156 addnwstr/window (stdscr)
157 addstr/window (stdscr)
158 addwstr/window (stdscr)
159 assume_default_colors/screen
160 attr_get/window (stdscr)
161 attr_off/window (stdscr)
162 attr_on/window (stdscr)
163 attr_set/window (stdscr)
164 attroff/window (stdscr)
165 attron/window (stdscr)
166 attrset/window (stdscr)
167 baudrate/screen
168 beep/screen
169 bkgd/window (stdscr)
170 bkgdset/window (stdscr)
171 bkgrnd/window (stdscr)
172 bkgrndset/window (stdscr)
173 boolcodes/global (readonly)
174 boolfnames/global (readonly)
175 boolnames/global (readonly)
176 border/window (stdscr)
177 border_set/window (stdscr)
178 box/window (stdscr)
179 box_set/window (stdscr)
180 can_change_color/terminal
181 cbreak/screen
182 chgat/window (stdscr)
183 clear/window (stdscr)
184 clearok/window
185 clrtobot/window (stdscr)
186 clrtoeol/window (stdscr)
187 color_content/screen
188 color_set/window (stdscr)
189 copywin/window locks(source, target)
190 cur_term/terminal
191 curs_set/screen
192 curscr/screen (readonly)
193 curses_version/global (readonly)
194 def_prog_mode/terminal
195 def_shell_mode/terminal
196 define_key/screen
197 del_curterm/screen
198 delay_output/screen
199 delch/window (stdscr)
200 deleteln/window (stdscr)
201 delscreen/global locks(screenlist, screen)
202 delwin/global locks(windowlist)
203 derwin/screen
204 doupdate/screen
205 dupwin/screen locks(window)
206 echo/screen
207 echo_wchar/window (stdscr)
208 echochar/window (stdscr)
209 endwin/screen
210 erase/window (stdscr)
211 erasechar/window (stdscr)
212 erasewchar/window (stdscr)
213 filter/global
214 flash/terminal
215 flushinp/screen
216 get_wch/screen (input-operation)
217 get_wstr/screen (input-operation)
218 getattrs/window
219 getbegx/window
220 getbegy/window
221 getbkgd/window
222 getbkgrnd/window
223 getcchar/reentrant
224 getch/screen (input-operation)
225 getcurx/window
226 getcury/window
227 getmaxx/window
228 getmaxy/window
229 getmouse/screen (input-operation)
230 getn_wstr/screen (input-operation)
231 getnstr/screen (input-operation)
232 getparx/window
233 getpary/window
234 getstr/screen (input-operation)
235 getwin/screen (input-operation)
236 halfdelay/screen
237 has_colors/terminal
238 has_ic/terminal
239 has_il/terminal
240 has_key/screen
241 hline/window (stdscr)
242 hline_set/window (stdscr)
243 idcok/window
244 idlok/window
245 immedok/window
246 in_wch/window (stdscr)
247 in_wchnstr/window (stdscr)
248 in_wchstr/window (stdscr)
249 inch/window (stdscr)
250 inchnstr/window (stdscr)
251 inchstr/window (stdscr)
252 init_color/screen
253 init_pair/screen
254 initscr/global locks(screenlist)
255 innstr/window (stdscr)
256 innwstr/window (stdscr)
257 ins_nwstr/window (stdscr)
258 ins_wch/window (stdscr)
259 ins_wstr/window (stdscr)
260 insch/window (stdscr)
261 insdelln/window (stdscr)
262 insertln/window (stdscr)
263 insnstr/window (stdscr)
264 insstr/window (stdscr)
265 instr/window (stdscr)
266 intrflush/terminal
267 inwstr/window (stdscr)
268 is_cleared/window
269 is_idcok/window
270 is_idlok/window
271 is_immedok/window
272 is_keypad/window
273 is_leaveok/window
274 is_linetouched/window
275 is_nodelay/window
276 is_notimeout/window
277 is_scrollok/window
278 is_syncok/window
279 is_term_resized/terminal
280 is_wintouched/window
281 isendwin/screen
282 key_defined/screen
283 key_name/global (static data)
284 keybound/screen
285 keyname/global (static data)
286 keyok/screen
287 keypad/window
288 killchar/terminal
289 killwchar/terminal
290 leaveok/window
291 longname/screen
292 mcprint/terminal
293 meta/screen
294 mouse_trafo/window (stdscr)
295 mouseinterval/screen
296 mousemask/screen
297 move/window (stdscr)
298 mvadd_wch/window (stdscr)
299 mvadd_wchnstr/window (stdscr)
300 mvadd_wchstr/window (stdscr)
301 mvaddch/window (stdscr)
302 mvaddchnstr/window (stdscr)
303 mvaddchstr/window (stdscr)
304 mvaddnstr/window (stdscr)
305 mvaddnwstr/window (stdscr)
306 mvaddstr/window (stdscr)
307 mvaddwstr/window (stdscr)
308 mvchgat/window (stdscr)
309 mvcur/screen
310 mvdelch/window (stdscr)
311 mvderwin/window (stdscr)
312 mvget_wch/screen (input-operation)
313 mvget_wstr/screen (input-operation)
314 mvgetch/screen (input-operation)
315 mvgetn_wstr/screen (input-operation)
316 mvgetnstr/screen (input-operation)
317 mvgetstr/screen (input-operation)
318 mvhline/window (stdscr)
319 mvhline_set/window (stdscr)
320 mvin_wch/window (stdscr)
321 mvin_wchnstr/window (stdscr)
322 mvin_wchstr/window (stdscr)
323 mvinch/window (stdscr)
324 mvinchnstr/window (stdscr)
325 mvinchstr/window (stdscr)
326 mvinnstr/window (stdscr)
327 mvinnwstr/window (stdscr)
328 mvins_nwstr/window (stdscr)
329 mvins_wch/window (stdscr)
330 mvins_wstr/window (stdscr)
331 mvinsch/window (stdscr)
332 mvinsnstr/window (stdscr)
333 mvinsstr/window (stdscr)
334 mvinstr/window (stdscr)
335 mvinwstr/window (stdscr)
336 mvprintw/window (stdscr)
337 mvscanw/screen
338 mvvline/window (stdscr)
339 mvvline_set/window (stdscr)
340 mvwadd_wch/window
341 mvwadd_wchnstr/window
342 mvwadd_wchstr/window
343 mvwaddch/window
344 mvwaddchnstr/window
345 mvwaddchstr/window
346 mvwaddnstr/window
347 mvwaddnwstr/window
348 mvwaddstr/window
349 mvwaddwstr/window
350 mvwchgat/window
351 mvwdelch/window
352 mvwget_wch/screen (input-operation)
353 mvwget_wstr/screen (input-operation)
354 mvwgetch/screen (input-operation)
355 mvwgetn_wstr/screen (input-operation)
356 mvwgetnstr/screen (input-operation)
357 mvwgetstr/screen (input-operation)
358 mvwhline/window
359 mvwhline_set/window
360 mvwin/window
361 mvwin_wch/window
362 mvwin_wchnstr/window
363 mvwin_wchstr/window
364 mvwinch/window
365 mvwinchnstr/window
366 mvwinchstr/window
367 mvwinnstr/window
368 mvwinnwstr/window
369 mvwins_nwstr/window
370 mvwins_wch/window
371 mvwins_wstr/window
372 mvwinsch/window
373 mvwinsnstr/window
374 mvwinsstr/window
375 mvwinstr/window
376 mvwinwstr/window
377 mvwprintw/window
378 mvwscanw/screen
379 mvwvline/window
380 mvwvline_set/window
381 napms/reentrant
382 newpad/global locks(windowlist)
383 newscr/screen (readonly)
384 newterm/global locks(screenlist)
385 newwin/global locks(windowlist)
386 nl/screen
387 nocbreak/screen
388 nodelay/window
389 noecho/screen
390 nofilter/global
391 nonl/screen
392 noqiflush/terminal
393 noraw/screen
394 notimeout/window
395 numcodes/global (readonly)
396 numfnames/global (readonly)
397 numnames/global (readonly)
398 ospeed/global
399 overlay/window locks(source, target)
400 overwrite/window locks(source, target)
401 pair_content/screen
402 pecho_wchar/screen
403 pechochar/screen
404 pnoutrefresh/screen
405 prefresh/screen
406 printw/window
407 putp/global
408 putwin/window
409 qiflush/terminal
410 raw/screen
411 redrawwin/window
412 refresh/screen
413 reset_prog_mode/screen
414 reset_shell_mode/screen
415 resetty/terminal
416 resize_term/screen locks(windowlist)
417 resizeterm/screen
418 restartterm/screen
419 ripoffline/global (static data)
420 savetty/terminal
421 scanw/screen
422 scr_dump/screen
423 scr_init/screen
424 scr_restore/screen
425 scr_set/screen
426 scrl/window (stdscr)
427 scroll/window
428 scrollok/window
429 set_curterm/screen
430 set_escdelay/screen
431 set_tabsize/screen
432 set_term/global locks(screenlist, screen)
433 setcchar/reentrant
434 setscrreg/window (stdscr)
435 setupterm/global
436 slk_attr/screen
437 slk_attr_off/screen
438 slk_attr_on/screen
439 slk_attr_set/screen
440 slk_attroff/screen
441 slk_attron/screen
442 slk_attrset/screen
443 slk_clear/screen
444 slk_color/screen
445 slk_init/screen
446 slk_label/screen
447 slk_noutrefresh/screen
448 slk_refresh/screen
449 slk_restore/screen
450 slk_set/screen
451 slk_touch/screen
452 slk_wset/screen
453 standend/window
454 standout/window
455 start_color/screen
456 stdscr/screen (readonly)
457 strcodes/global (readonly)
458 strfnames/global (readonly)
459 strnames/global (readonly)
460 subpad/window
461 subwin/window
462 syncok/window
463 term_attrs/screen
464 termattrs/screen
465 termname/terminal
466 tgetent/global
467 tgetflag/global
468 tgetnum/global
469 tgetstr/global
470 tgoto/global
471 tigetflag/terminal
472 tigetnum/terminal
473 tigetstr/terminal
474 timeout/window (stdscr)
475 touchline/window
476 touchwin/window
477 tparm/global (static data)
478 tputs/screen
479 trace/global (static data)
480 ttytype/screen (readonly)
481 typeahead/screen
482 unctrl/screen
483 unget_wch/screen (input-operation)
484 ungetch/screen (input-operation)
485 ungetmouse/screen (input-operation)
486 untouchwin/window
487 use_default_colors/screen
488 use_env/global (static data)
489 use_extended_names/global (static data)
490 use_legacy_coding/screen
491 use_screen/global locks(screenlist, screen)
492 use_window/global locks(windowlist, window)
493 vid_attr/screen
494 vid_puts/screen
495 vidattr/screen
496 vidputs/screen
497 vline/window (stdscr)
498 vline_set/window (stdscr)
499 vw_printw/window
500 vw_scanw/screen
501 vwprintw/window
502 vwscanw/screen
503 wadd_wch/window
504 wadd_wchnstr/window
505 wadd_wchstr/window
506 waddch/window
507 waddchnstr/window
508 waddchstr/window
509 waddnstr/window
510 waddnwstr/window
511 waddstr/window
512 waddwstr/window
513 wattr_get/window
514 wattr_off/window
515 wattr_on/window
516 wattr_set/window
517 wattroff/window
518 wattron/window
519 wattrset/window
520 wbkgd/window
521 wbkgdset/window
522 wbkgrnd/window
523 wbkgrndset/window
524 wborder/window
525 wborder_set/window
526 wchgat/window
527 wclear/window
528 wclrtobot/window
529 wclrtoeol/window
530 wcolor_set/window
531 wcursyncup/screen (affects window plus parents)
532 wdelch/window
533 wdeleteln/window
534 wecho_wchar/window
535 wechochar/window
536 wenclose/window
537 werase/window
538 wget_wch/screen (input-operation)
539 wget_wstr/screen (input-operation)
540 wgetbkgrnd/window
541 wgetch/screen (input-operation)
542 wgetdelay/window
543 wgetn_wstr/screen (input-operation)
544 wgetnstr/screen (input-operation)
545 wgetparent/window
546 wgetscrreg/window
547 wgetstr/screen (input-operation)
548 whline/window
549 whline_set/window
550 win_wch/window
551 win_wchnstr/window
552 win_wchstr/window
553 winch/window
554 winchnstr/window
555 winchstr/window
556 winnstr/window
557 winnwstr/window
558 wins_nwstr/window
559 wins_wch/window
560 wins_wstr/window
561 winsch/window
562 winsdelln/window
563 winsertln/window
564 winsnstr/window
565 winsstr/window
566 winstr/window
567 winwstr/window
568 wmouse_trafo/window
569 wmove/window
570 wnoutrefresh/screen
571 wprintw/window
572 wredrawln/window
573 wrefresh/screen
574 wresize/window locks(windowlist)
575 wscanw/screen
576 wscrl/window
577 wsetscrreg/window
578 wstandend/window
579 wstandout/window
580 wsyncdown/screen (affects window plus parents)
581 wsyncup/screen (affects window plus parents)
582 wtimeout/window
583 wtouchln/window
584 wunctrl/global (static data)
585 wvline/window
586 wvline_set/window
587 .TE
588 .\" ***************************************************************************
589 .SH RETURN VALUE
590 These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
591 .SH NOTES
592 Both a macro and a function are provided for each name.
593 .SH PORTABILITY
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.
598 .SH SEE ALSO
599 \fBcurses\fR(3X),
600 \fBcurs_opaque\fR(3X),
601 \fBcurs_variables\fR(3X).