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