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