2 ****************************************************************************
3 * Copyright (c) 2008-2012,2014 Free Software Foundation, Inc. *
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: *
13 * The above copyright notice and this permission notice shall be included *
14 * in all copies or substantial portions of the Software. *
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. *
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 *
28 ****************************************************************************
29 * @Id: curs_threads.3x,v 1.20 2014/03/15 19:25:28 tom Exp @
30 * ***************************************************************************
31 * ***************************************************************************
33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
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">
43 <H1>curs_threads 3x</H1>
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>
52 <H2><a name="h2-NAME">NAME</a></H2><PRE>
53 <STRONG>use_screen</STRONG>, <STRONG>use_window</STRONG> - <STRONG>curses</STRONG> thread support
57 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
58 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
60 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_WINDOW_CB)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
61 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_SCREEN_CB)(SCREEN</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
62 <STRONG>int</STRONG> <STRONG>get_escdelay(void);</STRONG>
63 <STRONG>int</STRONG> <STRONG>set_escdelay(int</STRONG> <STRONG>size);</STRONG>
64 <STRONG>int</STRONG> <STRONG>set_tabsize(int</STRONG> <STRONG>size);</STRONG>
65 <STRONG>int</STRONG> <STRONG>use_screen(SCREEN</STRONG> <STRONG>*scr,</STRONG> <STRONG>NCURSES_SCREEN_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG>
66 <STRONG>*data);</STRONG>
67 <STRONG>int</STRONG> <STRONG>use_window(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>NCURSES_WINDOW_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG>
68 <STRONG>*data);</STRONG>
72 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
73 This implementation can be configured to provide rudimen-
74 tary support for multi-threaded applications. This makes
75 a different set of libraries, e.g., <EM>libncursest</EM> since the
76 binary interfaces are different.
78 Rather than modify the interfaces to pass a thread speci-
79 fier to each function, it adds a few functions which can
80 be used in any configuration which hide the mutex's needed
81 to prevent concurrent use of the global variables when
82 configured for threading.
84 In addition to forcing access to members of the <STRONG>WINDOW</STRONG>
85 structure to be via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it
86 makes functions of the common global variables, e.g., COL-
87 ORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE curscr,
88 newscr and ttytype. Those variables are maintained as
89 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
91 Even this is not enough to make a thread-safe application
92 using curses. A multi-threaded application would be ex-
93 pected to have threads updating separate windows (within
94 the same device), or updating on separate screens (on dif-
95 ferent devices). Also, a few of the global variables are
96 considered writable by some applications. The functions
97 described here address these special situations.
99 The ESCDELAY and TABSIZE global variables are modified by
100 some applications. To modify them in any configuration,
101 use the <STRONG>set_escdelay</STRONG> or <STRONG>set_tabsize</STRONG> functions. Other
102 global variables are not modifiable.
104 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
106 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse
107 granularity mutexes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG>
108 parameters, and call a user-supplied function, passing it
109 a <EM>data</EM> parameter, and returning the value from the user-
110 supplied function to the application.
114 <H3><a name="h3-USAGE">USAGE</a></H3><PRE>
115 All of the ncurses library functions assume that the lo-
116 cale is not altered during operation. In addition, they
117 use data which is maintained within a hierarchy of scopes.
119 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo
120 or termcap interfaces.
122 <STRONG>o</STRONG> terminal data, e.g., associated with a call to
123 <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. The terminal data are initialized
124 when screens are created.
126 <STRONG>o</STRONG> screen data, e.g., associated with a call to
127 <EM>newterm</EM> or <EM>initscr</EM>.
129 <STRONG>o</STRONG> window data, e.g., associated with a call to <EM>newwin</EM>
130 or <EM>subwin</EM>. Windows are associated with screens.
131 Pads are not necessarily associated with a particu-
134 Most curses applications operate on one or more
135 windows within a single screen.
137 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as
140 This table lists the scope of data used for each symbol in
141 the ncurses library when it is configured to support
145 -------------------------------------------------------------
147 COLORS screen (readonly)
149 COLOR_PAIRS screen (readonly)
150 COLS screen (readonly)
151 ESCDELAY screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
152 LINES screen (readonly)
153 PAIR_NUMBER reentrant
156 TABSIZE screen (readonly)
158 acs_map screen (readonly)
159 add_wch window (stdscr)
160 add_wchnstr window (stdscr)
161 add_wchstr window (stdscr)
162 addch window (stdscr)
163 addchnstr window (stdscr)
164 addchstr window (stdscr)
165 addnstr window (stdscr)
166 addnwstr window (stdscr)
167 addstr window (stdscr)
168 addwstr window (stdscr)
169 assume_default_colors screen
170 attr_get window (stdscr)
171 attr_off window (stdscr)
172 attr_on window (stdscr)
173 attr_set window (stdscr)
174 attroff window (stdscr)
175 attron window (stdscr)
176 attrset window (stdscr)
180 bkgdset window (stdscr)
181 bkgrnd window (stdscr)
182 bkgrndset window (stdscr)
183 boolcodes global (readonly)
184 boolfnames global (readonly)
185 boolnames global (readonly)
186 border window (stdscr)
188 border_set window (stdscr)
190 box_set window (stdscr)
191 can_change_color terminal
193 chgat window (stdscr)
194 clear window (stdscr)
196 clrtobot window (stdscr)
197 clrtoeol window (stdscr)
199 color_set window (stdscr)
200 copywin window locks(source, target)
203 curscr screen (readonly)
204 curses_version global (readonly)
205 def_prog_mode terminal
206 def_shell_mode terminal
210 delch window (stdscr)
211 deleteln window (stdscr)
212 delscreen global locks(screenlist, screen)
213 delwin global locks(windowlist)
216 dupwin screen locks(window)
218 echo_wchar window (stdscr)
219 echochar window (stdscr)
221 erase window (stdscr)
222 erasechar window (stdscr)
223 erasewchar window (stdscr)
227 get_wch screen (input-operation)
228 get_wstr screen (input-operation)
235 getch screen (input-operation)
240 getmouse screen (input-operation)
241 getn_wstr screen (input-operation)
242 getnstr screen (input-operation)
245 getstr screen (input-operation)
246 getwin screen (input-operation)
252 hline window (stdscr)
253 hline_set window (stdscr)
258 in_wch window (stdscr)
259 in_wchnstr window (stdscr)
260 in_wchstr window (stdscr)
262 inchnstr window (stdscr)
263 inchstr window (stdscr)
266 initscr global locks(screenlist)
267 innstr window (stdscr)
268 innwstr window (stdscr)
269 ins_nwstr window (stdscr)
270 ins_wch window (stdscr)
271 ins_wstr window (stdscr)
272 insch window (stdscr)
273 insdelln window (stdscr)
274 insertln window (stdscr)
275 insnstr window (stdscr)
276 insstr window (stdscr)
277 instr window (stdscr)
279 inwstr window (stdscr)
286 is_linetouched window
291 is_term_resized terminal
295 key_name global (static data)
297 keyname global (static data)
306 mouse_trafo window (stdscr)
310 mvadd_wch window (stdscr)
311 mvadd_wchnstr window (stdscr)
312 mvadd_wchstr window (stdscr)
313 mvaddch window (stdscr)
314 mvaddchnstr window (stdscr)
315 mvaddchstr window (stdscr)
316 mvaddnstr window (stdscr)
317 mvaddnwstr window (stdscr)
318 mvaddstr window (stdscr)
319 mvaddwstr window (stdscr)
320 mvchgat window (stdscr)
323 mvdelch window (stdscr)
324 mvderwin window (stdscr)
325 mvget_wch screen (input-operation)
326 mvget_wstr screen (input-operation)
327 mvgetch screen (input-operation)
328 mvgetn_wstr screen (input-operation)
329 mvgetnstr screen (input-operation)
330 mvgetstr screen (input-operation)
331 mvhline window (stdscr)
332 mvhline_set window (stdscr)
333 mvin_wch window (stdscr)
334 mvin_wchnstr window (stdscr)
335 mvin_wchstr window (stdscr)
336 mvinch window (stdscr)
337 mvinchnstr window (stdscr)
338 mvinchstr window (stdscr)
339 mvinnstr window (stdscr)
340 mvinnwstr window (stdscr)
341 mvins_nwstr window (stdscr)
342 mvins_wch window (stdscr)
343 mvins_wstr window (stdscr)
344 mvinsch window (stdscr)
345 mvinsnstr window (stdscr)
346 mvinsstr window (stdscr)
347 mvinstr window (stdscr)
348 mvinwstr window (stdscr)
349 mvprintw window (stdscr)
351 mvvline window (stdscr)
352 mvvline_set window (stdscr)
354 mvwadd_wchnstr window
365 mvwget_wch screen (input-operation)
366 mvwget_wstr screen (input-operation)
367 mvwgetch screen (input-operation)
368 mvwgetn_wstr screen (input-operation)
369 mvwgetnstr screen (input-operation)
370 mvwgetstr screen (input-operation)
396 newpad global locks(windowlist)
397 newscr screen (readonly)
398 newterm global locks(screenlist)
399 newwin global locks(windowlist)
409 numcodes global (readonly)
410 numfnames global (readonly)
411 numnames global (readonly)
413 overlay window locks(source, target)
414 overwrite window locks(source, target)
427 reset_prog_mode screen
428 reset_shell_mode screen
430 resize_term screen locks(windowlist)
433 ripoffline global (static data)
446 set_term global locks(screenlist, screen)
448 setscrreg window (stdscr)
462 slk_noutrefresh screen
471 stdscr screen (readonly)
472 strcodes global (readonly)
473 strfnames global (readonly)
474 strnames global (readonly)
489 timeout window (stdscr)
492 tparm global (static data)
494 trace global (static data)
495 ttytype screen (readonly)
498 unget_wch screen (input-operation)
499 ungetch screen (input-operation)
500 ungetmouse screen (input-operation)
502 use_default_colors screen
503 use_env global (static data)
504 use_extended_names global (static data)
505 use_legacy_coding screen
506 use_screen global locks(screenlist, screen)
507 use_window global locks(windowlist, window)
512 vline window (stdscr)
513 vline_set window (stdscr)
547 wcursyncup screen (affects window plus parents)
554 wget_wch screen (input-operation)
555 wget_wstr screen (input-operation)
557 wgetch screen (input-operation)
559 wgetn_wstr screen (input-operation)
560 wgetnstr screen (input-operation)
563 wgetstr screen (input-operation)
591 wresize window locks(windowlist)
597 wsyncdown screen (affects window plus parents)
598 wsyncup screen (affects window plus parents)
601 wunctrl global (static data)
607 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
608 These functions all return TRUE or FALSE, except as noted.
612 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
613 Both a macro and a function are provided for each name.
617 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
618 These routines are specific to ncurses. They were not
619 supported on Version 7, BSD or System V implementations.
620 It is recommended that any code depending on ncurses ex-
621 tensions be conditioned using NCURSES_VERSION.
625 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
626 <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>.
630 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
634 <li><a href="#h2-NAME">NAME</a></li>
635 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
636 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
638 <li><a href="#h3-USAGE">USAGE</a></li>
641 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
642 <li><a href="#h2-NOTES">NOTES</a></li>
643 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
644 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>