Gitiles
Code Review Sign In
gerrit.omnirom.org / android_external_libncurses / e6a01f5727d104ee88c228bc866a505de770c1b2 / . / doc / html / man / curs_threads.3x.html
blob: 2a2f0fd98a9caec76e66af14e23397f8ca9ad140 [file] [log] [blame]
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame^]1<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2<!--
3 ****************************************************************************
4 * Copyright (c) 2008 Free Software Foundation, Inc. *
5 * *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
13 * *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
16 * *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
28 * authorization. *
29 ****************************************************************************
30 * @Id: curs_threads.3x,v 1.12 2008/04/12 18:22:51 tom Exp @
31 * ***************************************************************************
32 * ***************************************************************************
33-->
34<HTML>
35<HEAD>
36<TITLE>curs_threads 3x</TITLE>
37<link rev=made href="mailto:bug-ncurses@gnu.org">
38<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
39</HEAD>
40<BODY>
41<H1>curs_threads 3x</H1>
42<HR>
43<PRE>
44<!-- Manpage converted by man2html 3.0.1 -->
45<STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
46
47
48
49
50</PRE>
51<H2>NAME</H2><PRE>
52 <STRONG>use_screen</STRONG>, <STRONG>use_window</STRONG> - <STRONG>curses</STRONG> thread support
53
54
55</PRE>
56<H2>SYNOPSIS</H2><PRE>
57 <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
58
59 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_WINDOW_CB)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG> <STRONG>type-</STRONG>
60 <STRONG>def</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_SCREEN_CB)(SCREEN</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
61 <STRONG>int</STRONG> <STRONG>set_escdelay(int</STRONG> <STRONG>size);</STRONG>
62 <STRONG>int</STRONG> <STRONG>set_tabsize(int</STRONG> <STRONG>size);</STRONG>
63 <STRONG>int</STRONG> <STRONG>use_screen(SCREEN</STRONG> <STRONG>*scr,</STRONG> <STRONG>NCURSES_WINDOW_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG>
64 <STRONG>*data);</STRONG>
65 <STRONG>int</STRONG> <STRONG>use_window(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>NCURSES_SCREEN_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG>
66 <STRONG>*data);</STRONG>
67
68
69</PRE>
70<H2>DESCRIPTION</H2><PRE>
71 This implementation can be configured to provide rudimen-
72 tary support for multi-threaded applications. This makes
73 a different set of libraries, e.g., <EM>libncursest</EM> since the
74 binary interfaces are different.
75
76 Rather than modify the interfaces to pass a thread speci-
77 fier to each function, it adds a few functions which can
78 be used in any configuration which hide the mutex's needed
79 to prevent concurrent use of the global variables when
80 configured for threading.
81
82 In addition to forcing access to members of the <STRONG>WINDOW</STRONG>
83 structure to be via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it
84 makes functions of the common global variables, e.g., COL-
85 ORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE curscr,
86 newscr and ttytype. Those variables are maintained as
87 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
88
89 Even this is not enough to make a thread-safe application
90 using curses. A multi-threaded application would be ex-
91 pected to have threads updating separate windows (within
92 the same device), or updating on separate screens (on dif-
93 ferent devices). Also, a few of the global variables are
94 considered writable by some applications. The functions
95 described here address these special situations.
96
97 The ESCDELAY and TABSIZE global variables are modified by
98 some applications. To modify them in any configuration,
99 use the <STRONG>set_escdelay</STRONG> or <STRONG>set_tabsize</STRONG> functions. Other
100 global variables are not modifiable.
101
102 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse
103 granularity mutexes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG>
104 parameters, and call a user-supplied function, passing it
105 a <EM>data</EM> parameter, and returning the value from the user-
106 supplied function to the application.
107
108 <STRONG>USAGE</STRONG>
109 All of the ncurses library functions assume that the lo-
110 cale is not altered during operation. In addition, they
111 use data which is maintained within a hierarchy of scopes.
112
113 - global data, e.g., used in the low-level termin-
114 fo or termcap interfaces.
115
116 - terminal data, e.g., associated with a call to
117 <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. The terminal data are initialized
118 when screens are created.
119
120 - screen data, e.g., associated with a call to
121 <EM>newterm</EM> or <EM>initscr</EM>.
122
123 - window data, e.g., associated with a call to
124 <EM>newwin</EM> or <EM>subwin</EM>. Windows are associated with
125 screens. Pads are not necessarily associated
126 with a particular screen.
127
128 Most curses applications operate on one or more
129 windows within a single screen.
130
131 - reentrant, i.e., it uses only the data passed as
132 parameters.
133
134 This table lists the scope of data used for each symbol in
135 the ncurses library when it is configured to support
136 threading:
137
138 Symbol Scope
139 -------------------------------------------------------------
140 BC global
141 COLORS screen (readonly)
142 COLOR_PAIR reentrant
143 COLOR_PAIRS screen (readonly)
144 COLS screen (readonly)
145 ESCDELAY screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
146 LINES screen (readonly)
147 PAIR_NUMBER reentrant
148 PC global
149 SP global
150 TABSIZE screen (readonly)
151 UP global
152 acs_map screen (readonly)
153 add_wch window (stdscr)
154 add_wchnstr window (stdscr)
155 add_wchstr window (stdscr)
156 addch window (stdscr)
157 addchnstr window (stdscr)
158 addchstr window (stdscr)
159 addnstr window (stdscr)
160 addnwstr window (stdscr)
161 addstr window (stdscr)
162 addwstr window (stdscr)
163 assume_default_colors screen
164 attr_get window (stdscr)
165 attr_off window (stdscr)
166 attr_on window (stdscr)
167 attr_set window (stdscr)
168 attroff window (stdscr)
169 attron window (stdscr)
170 attrset window (stdscr)
171 baudrate screen
172 beep screen
173 bkgd window (stdscr)
174 bkgdset window (stdscr)
175 bkgrnd window (stdscr)
176 bkgrndset window (stdscr)
177 boolcodes global (readonly)
178 boolfnames global (readonly)
179 boolnames global (readonly)
180 border window (stdscr)
181 border_set window (stdscr)
182 box window (stdscr)
183 box_set window (stdscr)
184
185 can_change_color terminal
186 cbreak screen
187 chgat window (stdscr)
188 clear window (stdscr)
189 clearok window
190 clrtobot window (stdscr)
191 clrtoeol window (stdscr)
192 color_content screen
193 color_set window (stdscr)
194 copywin window locks(source, target)
195 cur_term terminal
196 curs_set screen
197 curscr screen (readonly)
198 curses_version global (readonly)
199 def_prog_mode terminal
200 def_shell_mode terminal
201 define_key screen
202 del_curterm screen
203 delay_output screen
204 delch window (stdscr)
205 deleteln window (stdscr)
206 delscreen global locks(screenlist, screen)
207 delwin global locks(windowlist)
208 derwin screen
209 doupdate screen
210 dupwin screen locks(window)
211 echo screen
212 echo_wchar window (stdscr)
213 echochar window (stdscr)
214 endwin screen
215 erase window (stdscr)
216 erasechar window (stdscr)
217 erasewchar window (stdscr)
218 filter global
219 flash terminal
220 flushinp screen
221 get_wch screen (input-operation)
222 get_wstr screen (input-operation)
223 getattrs window
224 getbegx window
225 getbegy window
226 getbkgd window
227 getbkgrnd window
228 getcchar reentrant
229 getch screen (input-operation)
230 getcurx window
231 getcury window
232 getmaxx window
233 getmaxy window
234 getmouse screen (input-operation)
235 getn_wstr screen (input-operation)
236 getnstr screen (input-operation)
237 getparx window
238 getpary window
239 getstr screen (input-operation)
240 getwin screen (input-operation)
241 halfdelay screen
242 has_colors terminal
243 has_ic terminal
244 has_il terminal
245 has_key screen
246 hline window (stdscr)
247 hline_set window (stdscr)
248 idcok window
249 idlok window
250 immedok window
251
252 in_wch window (stdscr)
253 in_wchnstr window (stdscr)
254 in_wchstr window (stdscr)
255 inch window (stdscr)
256 inchnstr window (stdscr)
257 inchstr window (stdscr)
258 init_color screen
259 init_pair screen
260 initscr global locks(screenlist)
261 innstr window (stdscr)
262 innwstr window (stdscr)
263 ins_nwstr window (stdscr)
264 ins_wch window (stdscr)
265 ins_wstr window (stdscr)
266 insch window (stdscr)
267 insdelln window (stdscr)
268 insertln window (stdscr)
269 insnstr window (stdscr)
270 insstr window (stdscr)
271 instr window (stdscr)
272 intrflush terminal
273 inwstr window (stdscr)
274 is_cleared window
275 is_idcok window
276 is_idlok window
277 is_immedok window
278 is_keypad window
279 is_leaveok window
280 is_linetouched window
281 is_nodelay window
282 is_notimeout window
283 is_scrollok window
284 is_syncok window
285 is_term_resized terminal
286 is_wintouched window
287 isendwin screen
288 key_defined screen
289 key_name global (static data)
290 keybound screen
291 keyname global (static data)
292 keyok screen
293 keypad window
294 killchar terminal
295 killwchar terminal
296 leaveok window
297 longname screen
298 mcprint terminal
299 meta screen
300 mouse_trafo window (stdscr)
301 mouseinterval screen
302 mousemask screen
303 move window (stdscr)
304 mvadd_wch window (stdscr)
305 mvadd_wchnstr window (stdscr)
306 mvadd_wchstr window (stdscr)
307 mvaddch window (stdscr)
308 mvaddchnstr window (stdscr)
309 mvaddchstr window (stdscr)
310 mvaddnstr window (stdscr)
311 mvaddnwstr window (stdscr)
312 mvaddstr window (stdscr)
313 mvaddwstr window (stdscr)
314 mvchgat window (stdscr)
315 mvcur screen
316 mvdelch window (stdscr)
317 mvderwin window (stdscr)
318
319 mvget_wch screen (input-operation)
320 mvget_wstr screen (input-operation)
321 mvgetch screen (input-operation)
322 mvgetn_wstr screen (input-operation)
323 mvgetnstr screen (input-operation)
324 mvgetstr screen (input-operation)
325 mvhline window (stdscr)
326 mvhline_set window (stdscr)
327 mvin_wch window (stdscr)
328 mvin_wchnstr window (stdscr)
329 mvin_wchstr window (stdscr)
330 mvinch window (stdscr)
331 mvinchnstr window (stdscr)
332 mvinchstr window (stdscr)
333 mvinnstr window (stdscr)
334 mvinnwstr window (stdscr)
335 mvins_nwstr window (stdscr)
336 mvins_wch window (stdscr)
337 mvins_wstr window (stdscr)
338 mvinsch window (stdscr)
339 mvinsnstr window (stdscr)
340 mvinsstr window (stdscr)
341 mvinstr window (stdscr)
342 mvinwstr window (stdscr)
343 mvprintw window (stdscr)
344 mvscanw screen
345 mvvline window (stdscr)
346 mvvline_set window (stdscr)
347 mvwadd_wch window
348 mvwadd_wchnstr window
349 mvwadd_wchstr window
350 mvwaddch window
351 mvwaddchnstr window
352 mvwaddchstr window
353 mvwaddnstr window
354 mvwaddnwstr window
355 mvwaddstr window
356 mvwaddwstr window
357 mvwchgat window
358 mvwdelch window
359 mvwget_wch screen (input-operation)
360 mvwget_wstr screen (input-operation)
361 mvwgetch screen (input-operation)
362 mvwgetn_wstr screen (input-operation)
363 mvwgetnstr screen (input-operation)
364 mvwgetstr screen (input-operation)
365 mvwhline window
366 mvwhline_set window
367 mvwin window
368 mvwin_wch window
369 mvwin_wchnstr window
370 mvwin_wchstr window
371 mvwinch window
372 mvwinchnstr window
373 mvwinchstr window
374 mvwinnstr window
375 mvwinnwstr window
376 mvwins_nwstr window
377 mvwins_wch window
378 mvwins_wstr window
379 mvwinsch window
380 mvwinsnstr window
381 mvwinsstr window
382 mvwinstr window
383 mvwinwstr window
384 mvwprintw window
385
386 mvwscanw screen
387 mvwvline window
388 mvwvline_set window
389 napms reentrant
390 newpad global locks(windowlist)
391 newscr screen (readonly)
392 newterm global locks(screenlist)
393 newwin global locks(windowlist)
394 nl screen
395 nocbreak screen
396 nodelay window
397 noecho screen
398 nofilter global
399 nonl screen
400 noqiflush terminal
401 noraw screen
402 notimeout window
403 numcodes global (readonly)
404 numfnames global (readonly)
405 numnames global (readonly)
406 ospeed global
407 overlay window locks(source, target)
408 overwrite window locks(source, target)
409 pair_content screen
410 pecho_wchar screen
411 pechochar screen
412 pnoutrefresh screen
413 prefresh screen
414 printw window
415 putp global
416 putwin window
417 qiflush terminal
418 raw screen
419 redrawwin window
420 refresh screen
421 reset_prog_mode screen
422 reset_shell_mode screen
423 resetty terminal
424 resize_term screen locks(windowlist)
425 resizeterm screen
426 restartterm screen
427 ripoffline global (static data)
428 savetty terminal
429 scanw screen
430 scr_dump screen
431 scr_init screen
432 scr_restore screen
433 scr_set screen
434 scrl window (stdscr)
435 scroll window
436 scrollok window
437 set_curterm screen
438 set_escdelay screen
439 set_tabsize screen
440 set_term global locks(screenlist, screen)
441 setcchar reentrant
442 setscrreg window (stdscr)
443 setupterm global
444 slk_attr screen
445 slk_attr_off screen
446 slk_attr_on screen
447 slk_attr_set screen
448 slk_attroff screen
449 slk_attron screen
450 slk_attrset screen
451 slk_clear screen
452
453 slk_color screen
454 slk_init screen
455 slk_label screen
456 slk_noutrefresh screen
457 slk_refresh screen
458 slk_restore screen
459 slk_set screen
460 slk_touch screen
461 slk_wset screen
462 standend window
463 standout window
464 start_color screen
465 stdscr screen (readonly)
466 strcodes global (readonly)
467 strfnames global (readonly)
468 strnames global (readonly)
469 subpad window
470 subwin window
471 syncok window
472 term_attrs screen
473 termattrs screen
474 termname terminal
475 tgetent global
476 tgetflag global
477 tgetnum global
478 tgetstr global
479 tgoto global
480 tigetflag terminal
481 tigetnum terminal
482 tigetstr terminal
483 timeout window (stdscr)
484 touchline window
485 touchwin window
486 tparm global (static data)
487 tputs screen
488 trace global (static data)
489 ttytype screen (readonly)
490 typeahead screen
491 unctrl screen
492 unget_wch screen (input-operation)
493 ungetch screen (input-operation)
494 ungetmouse screen (input-operation)
495 untouchwin window
496 use_default_colors screen
497 use_env global (static data)
498 use_extended_names global (static data)
499 use_legacy_coding screen
500 use_screen global locks(screenlist, screen)
501 use_window global locks(windowlist, window)
502 vid_attr screen
503 vid_puts screen
504 vidattr screen
505 vidputs screen
506 vline window (stdscr)
507 vline_set window (stdscr)
508 vw_printw window
509 vw_scanw screen
510 vwprintw window
511 vwscanw screen
512 wadd_wch window
513 wadd_wchnstr window
514 wadd_wchstr window
515 waddch window
516 waddchnstr window
517 waddchstr window
518 waddnstr window
519
520 waddnwstr window
521 waddstr window
522 waddwstr window
523 wattr_get window
524 wattr_off window
525 wattr_on window
526 wattr_set window
527 wattroff window
528 wattron window
529 wattrset window
530 wbkgd window
531 wbkgdset window
532 wbkgrnd window
533 wbkgrndset window
534 wborder window
535 wborder_set window
536 wchgat window
537 wclear window
538 wclrtobot window
539 wclrtoeol window
540 wcolor_set window
541 wcursyncup screen (affects window plus parents)
542 wdelch window
543 wdeleteln window
544 wecho_wchar window
545 wechochar window
546 wenclose window
547 werase window
548 wget_wch screen (input-operation)
549 wget_wstr screen (input-operation)
550 wgetbkgrnd window
551 wgetch screen (input-operation)
552 wgetn_wstr screen (input-operation)
553 wgetnstr screen (input-operation)
554 wgetparent window
555 wgetscrreg window
556 wgetstr screen (input-operation)
557 whline window
558 whline_set window
559 win_wch window
560 win_wchnstr window
561 win_wchstr window
562 winch window
563 winchnstr window
564 winchstr window
565 winnstr window
566 winnwstr window
567 wins_nwstr window
568 wins_wch window
569 wins_wstr window
570 winsch window
571 winsdelln window
572 winsertln window
573 winsnstr window
574 winsstr window
575 winstr window
576 winwstr window
577 wmouse_trafo window
578 wmove window
579 wnoutrefresh screen
580 wprintw window
581 wredrawln window
582 wrefresh screen
583 wresize window locks(windowlist)
584 wscanw screen
585 wscrl window
586
587 wsetscrreg window
588 wstandend window
589 wstandout window
590 wsyncdown screen (affects window plus parents)
591 wsyncup screen (affects window plus parents)
592 wtimeout window
593 wtouchln window
594 wunctrl global (static data)
595 wvline window
596 wvline_set window
597
598
599</PRE>
600<H2>RETURN VALUE</H2><PRE>
601 These functions all return TRUE or FALSE, except as noted.
602
603
604</PRE>
605<H2>NOTES</H2><PRE>
606 Both a macro and a function are provided for each name.
607
608
609</PRE>
610<H2>PORTABILITY</H2><PRE>
611 These routines are specific to ncurses. They were not
612 supported on Version 7, BSD or System V implementations.
613 It is recommended that any code depending on ncurses ex-
614 tensions be conditioned using NCURSES_VERSION.
615
616
617</PRE>
618<H2>SEE ALSO</H2><PRE>
619 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>
620
621
622
623 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
624</PRE>
625<HR>
626<ADDRESS>
627Man(1) output converted with
628<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
629</ADDRESS>
630</BODY>
631</HTML>