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