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