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