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