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