1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
3 ****************************************************************************
4 * Copyright (c) 2008-2010,2012 Free Software Foundation, Inc. *
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: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
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. *
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 *
29 ****************************************************************************
30 * @Id: curs_threads.3x,v 1.19 2012/05/26 17:03:26 tom Exp @
31 * ***************************************************************************
32 * ***************************************************************************
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">
41 <H1>curs_threads 3x</H1>
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>
52 <STRONG>use_screen</STRONG>, <STRONG>use_window</STRONG> - <STRONG>curses</STRONG> thread support
56 <H2>SYNOPSIS</H2><PRE>
57 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
59 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_WINDOW_CB)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
60 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_SCREEN_CB)(SCREEN</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
61 <STRONG>int</STRONG> <STRONG>get_escdelay(void);</STRONG>
62 <STRONG>int</STRONG> <STRONG>set_escdelay(int</STRONG> <STRONG>size);</STRONG>
63 <STRONG>int</STRONG> <STRONG>set_tabsize(int</STRONG> <STRONG>size);</STRONG>
64 <STRONG>int</STRONG> <STRONG>use_screen(SCREEN</STRONG> <STRONG>*scr,</STRONG> <STRONG>NCURSES_SCREEN_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG>
65 <STRONG>*data);</STRONG>
66 <STRONG>int</STRONG> <STRONG>use_window(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>NCURSES_WINDOW_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG>
67 <STRONG>*data);</STRONG>
71 <H2>DESCRIPTION</H2><PRE>
72 This implementation can be configured to provide rudimen-
73 tary support for multi-threaded applications. This makes
74 a different set of libraries, e.g., <EM>libncursest</EM> since the
75 binary interfaces are different.
77 Rather than modify the interfaces to pass a thread speci-
78 fier to each function, it adds a few functions which can
79 be used in any configuration which hide the mutex's needed
80 to prevent concurrent use of the global variables when
81 configured for threading.
83 In addition to forcing access to members of the <STRONG>WINDOW</STRONG>
84 structure to be via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it
85 makes functions of the common global variables, e.g., COL-
86 ORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE curscr,
87 newscr and ttytype. Those variables are maintained as
88 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
90 Even this is not enough to make a thread-safe application
91 using curses. A multi-threaded application would be ex-
92 pected to have threads updating separate windows (within
93 the same device), or updating on separate screens (on dif-
94 ferent devices). Also, a few of the global variables are
95 considered writable by some applications. The functions
96 described here address these special situations.
98 The ESCDELAY and TABSIZE global variables are modified by
99 some applications. To modify them in any configuration,
100 use the <STRONG>set_escdelay</STRONG> or <STRONG>set_tabsize</STRONG> functions. Other
101 global variables are not modifiable.
103 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
105 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse
106 granularity mutexes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG>
107 parameters, and call a user-supplied function, passing it
108 a <EM>data</EM> parameter, and returning the value from the user-
109 supplied function to the application.
111 <STRONG>USAGE</STRONG>
112 All of the ncurses library functions assume that the lo-
113 cale is not altered during operation. In addition, they
114 use data which is maintained within a hierarchy of scopes.
116 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo
117 or termcap interfaces.
119 <STRONG>o</STRONG> terminal data, e.g., associated with a call to
120 <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. The terminal data are initialized
121 when screens are created.
123 <STRONG>o</STRONG> screen data, e.g., associated with a call to
124 <EM>newterm</EM> or <EM>initscr</EM>.
126 <STRONG>o</STRONG> window data, e.g., associated with a call to <EM>newwin</EM>
127 or <EM>subwin</EM>. Windows are associated with screens.
128 Pads are not necessarily associated with a particu-
131 Most curses applications operate on one or more
132 windows within a single screen.
134 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as
137 This table lists the scope of data used for each symbol in
138 the ncurses library when it is configured to support
142 -------------------------------------------------------------
144 COLORS screen (readonly)
146 COLOR_PAIRS screen (readonly)
147 COLS screen (readonly)
148 ESCDELAY screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
149 LINES screen (readonly)
150 PAIR_NUMBER reentrant
153 TABSIZE screen (readonly)
155 acs_map screen (readonly)
156 add_wch window (stdscr)
157 add_wchnstr window (stdscr)
158 add_wchstr window (stdscr)
159 addch window (stdscr)
160 addchnstr window (stdscr)
161 addchstr window (stdscr)
162 addnstr window (stdscr)
163 addnwstr window (stdscr)
164 addstr window (stdscr)
165 addwstr window (stdscr)
166 assume_default_colors screen
167 attr_get window (stdscr)
168 attr_off window (stdscr)
169 attr_on window (stdscr)
170 attr_set window (stdscr)
171 attroff window (stdscr)
172 attron window (stdscr)
173 attrset window (stdscr)
177 bkgdset window (stdscr)
178 bkgrnd window (stdscr)
179 bkgrndset window (stdscr)
180 boolcodes global (readonly)
181 boolfnames global (readonly)
182 boolnames global (readonly)
183 border window (stdscr)
185 border_set window (stdscr)
187 box_set window (stdscr)
188 can_change_color terminal
190 chgat window (stdscr)
191 clear window (stdscr)
193 clrtobot window (stdscr)
194 clrtoeol window (stdscr)
196 color_set window (stdscr)
197 copywin window locks(source, target)
200 curscr screen (readonly)
201 curses_version global (readonly)
202 def_prog_mode terminal
203 def_shell_mode terminal
207 delch window (stdscr)
208 deleteln window (stdscr)
209 delscreen global locks(screenlist, screen)
210 delwin global locks(windowlist)
213 dupwin screen locks(window)
215 echo_wchar window (stdscr)
216 echochar window (stdscr)
218 erase window (stdscr)
219 erasechar window (stdscr)
220 erasewchar window (stdscr)
224 get_wch screen (input-operation)
225 get_wstr screen (input-operation)
232 getch screen (input-operation)
237 getmouse screen (input-operation)
238 getn_wstr screen (input-operation)
239 getnstr screen (input-operation)
242 getstr screen (input-operation)
243 getwin screen (input-operation)
249 hline window (stdscr)
250 hline_set window (stdscr)
255 in_wch window (stdscr)
256 in_wchnstr window (stdscr)
257 in_wchstr window (stdscr)
259 inchnstr window (stdscr)
260 inchstr window (stdscr)
263 initscr global locks(screenlist)
264 innstr window (stdscr)
265 innwstr window (stdscr)
266 ins_nwstr window (stdscr)
267 ins_wch window (stdscr)
268 ins_wstr window (stdscr)
269 insch window (stdscr)
270 insdelln window (stdscr)
271 insertln window (stdscr)
272 insnstr window (stdscr)
273 insstr window (stdscr)
274 instr window (stdscr)
276 inwstr window (stdscr)
283 is_linetouched window
288 is_term_resized terminal
292 key_name global (static data)
294 keyname global (static data)
303 mouse_trafo window (stdscr)
307 mvadd_wch window (stdscr)
308 mvadd_wchnstr window (stdscr)
309 mvadd_wchstr window (stdscr)
310 mvaddch window (stdscr)
311 mvaddchnstr window (stdscr)
312 mvaddchstr window (stdscr)
313 mvaddnstr window (stdscr)
314 mvaddnwstr window (stdscr)
315 mvaddstr window (stdscr)
316 mvaddwstr window (stdscr)
317 mvchgat window (stdscr)
320 mvdelch window (stdscr)
321 mvderwin window (stdscr)
322 mvget_wch screen (input-operation)
323 mvget_wstr screen (input-operation)
324 mvgetch screen (input-operation)
325 mvgetn_wstr screen (input-operation)
326 mvgetnstr screen (input-operation)
327 mvgetstr screen (input-operation)
328 mvhline window (stdscr)
329 mvhline_set window (stdscr)
330 mvin_wch window (stdscr)
331 mvin_wchnstr window (stdscr)
332 mvin_wchstr window (stdscr)
333 mvinch window (stdscr)
334 mvinchnstr window (stdscr)
335 mvinchstr window (stdscr)
336 mvinnstr window (stdscr)
337 mvinnwstr window (stdscr)
338 mvins_nwstr window (stdscr)
339 mvins_wch window (stdscr)
340 mvins_wstr window (stdscr)
341 mvinsch window (stdscr)
342 mvinsnstr window (stdscr)
343 mvinsstr window (stdscr)
344 mvinstr window (stdscr)
345 mvinwstr window (stdscr)
346 mvprintw window (stdscr)
348 mvvline window (stdscr)
349 mvvline_set window (stdscr)
351 mvwadd_wchnstr window
362 mvwget_wch screen (input-operation)
363 mvwget_wstr screen (input-operation)
364 mvwgetch screen (input-operation)
365 mvwgetn_wstr screen (input-operation)
366 mvwgetnstr screen (input-operation)
367 mvwgetstr screen (input-operation)
393 newpad global locks(windowlist)
394 newscr screen (readonly)
395 newterm global locks(screenlist)
396 newwin global locks(windowlist)
406 numcodes global (readonly)
407 numfnames global (readonly)
408 numnames global (readonly)
410 overlay window locks(source, target)
411 overwrite window locks(source, target)
424 reset_prog_mode screen
425 reset_shell_mode screen
427 resize_term screen locks(windowlist)
430 ripoffline global (static data)
443 set_term global locks(screenlist, screen)
445 setscrreg window (stdscr)
459 slk_noutrefresh screen
468 stdscr screen (readonly)
469 strcodes global (readonly)
470 strfnames global (readonly)
471 strnames global (readonly)
486 timeout window (stdscr)
489 tparm global (static data)
491 trace global (static data)
492 ttytype screen (readonly)
495 unget_wch screen (input-operation)
496 ungetch screen (input-operation)
497 ungetmouse screen (input-operation)
499 use_default_colors screen
500 use_env global (static data)
501 use_extended_names global (static data)
502 use_legacy_coding screen
503 use_screen global locks(screenlist, screen)
504 use_window global locks(windowlist, window)
509 vline window (stdscr)
510 vline_set window (stdscr)
544 wcursyncup screen (affects window plus parents)
551 wget_wch screen (input-operation)
552 wget_wstr screen (input-operation)
554 wgetch screen (input-operation)
555 wgetn_wstr screen (input-operation)
556 wgetnstr screen (input-operation)
559 wgetstr screen (input-operation)
587 wresize window locks(windowlist)
593 wsyncdown screen (affects window plus parents)
594 wsyncup screen (affects window plus parents)
597 wunctrl global (static data)
603 <H2>RETURN VALUE</H2><PRE>
604 These functions all return TRUE or FALSE, except as noted.
609 Both a macro and a function are provided for each name.
613 <H2>PORTABILITY</H2><PRE>
614 These routines are specific to ncurses. They were not
615 supported on Version 7, BSD or System V implementations.
616 It is recommended that any code depending on ncurses ex-
617 tensions be conditioned using NCURSES_VERSION.
621 <H2>SEE ALSO</H2><PRE>
622 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
626 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
630 Man(1) output converted with
631 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>