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