1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 2008 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.12 2008/04/12 18:22:51 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> <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>
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.
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.
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.
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.
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.
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.
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.
113 - global data, e.g., used in the low-level termin-
114 fo or termcap interfaces.
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.
120 - screen data, e.g., associated with a call to
121 <EM>newterm</EM> or <EM>initscr</EM>.
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.
128 Most curses applications operate on one or more
129 windows within a single screen.
131 - reentrant, i.e., it uses only the data passed as
134 This table lists the scope of data used for each symbol in
135 the ncurses library when it is configured to support
139 -------------------------------------------------------------
141 COLORS screen (readonly)
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
150 TABSIZE screen (readonly)
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)
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)
183 box_set window (stdscr)
185 can_change_color terminal
187 chgat window (stdscr)
188 clear window (stdscr)
190 clrtobot window (stdscr)
191 clrtoeol window (stdscr)
193 color_set window (stdscr)
194 copywin window locks(source, target)
197 curscr screen (readonly)
198 curses_version global (readonly)
199 def_prog_mode terminal
200 def_shell_mode terminal
204 delch window (stdscr)
205 deleteln window (stdscr)
206 delscreen global locks(screenlist, screen)
207 delwin global locks(windowlist)
210 dupwin screen locks(window)
212 echo_wchar window (stdscr)
213 echochar window (stdscr)
215 erase window (stdscr)
216 erasechar window (stdscr)
217 erasewchar window (stdscr)
221 get_wch screen (input-operation)
222 get_wstr screen (input-operation)
229 getch screen (input-operation)
234 getmouse screen (input-operation)
235 getn_wstr screen (input-operation)
236 getnstr screen (input-operation)
239 getstr screen (input-operation)
240 getwin screen (input-operation)
246 hline window (stdscr)
247 hline_set window (stdscr)
252 in_wch window (stdscr)
253 in_wchnstr window (stdscr)
254 in_wchstr window (stdscr)
256 inchnstr window (stdscr)
257 inchstr window (stdscr)
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)
273 inwstr window (stdscr)
280 is_linetouched window
285 is_term_resized terminal
289 key_name global (static data)
291 keyname global (static data)
300 mouse_trafo 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)
316 mvdelch window (stdscr)
317 mvderwin window (stdscr)
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)
345 mvvline window (stdscr)
346 mvvline_set window (stdscr)
348 mvwadd_wchnstr 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)
390 newpad global locks(windowlist)
391 newscr screen (readonly)
392 newterm global locks(screenlist)
393 newwin global locks(windowlist)
403 numcodes global (readonly)
404 numfnames global (readonly)
405 numnames global (readonly)
407 overlay window locks(source, target)
408 overwrite window locks(source, target)
421 reset_prog_mode screen
422 reset_shell_mode screen
424 resize_term screen locks(windowlist)
427 ripoffline global (static data)
440 set_term global locks(screenlist, screen)
442 setscrreg window (stdscr)
456 slk_noutrefresh screen
465 stdscr screen (readonly)
466 strcodes global (readonly)
467 strfnames global (readonly)
468 strnames global (readonly)
483 timeout window (stdscr)
486 tparm global (static data)
488 trace global (static data)
489 ttytype screen (readonly)
492 unget_wch screen (input-operation)
493 ungetch screen (input-operation)
494 ungetmouse screen (input-operation)
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)
506 vline window (stdscr)
507 vline_set window (stdscr)
541 wcursyncup screen (affects window plus parents)
548 wget_wch screen (input-operation)
549 wget_wstr screen (input-operation)
551 wgetch screen (input-operation)
552 wgetn_wstr screen (input-operation)
553 wgetnstr screen (input-operation)
556 wgetstr screen (input-operation)
583 wresize window locks(windowlist)
590 wsyncdown screen (affects window plus parents)
591 wsyncup screen (affects window plus parents)
594 wunctrl global (static data)
600 <H2>RETURN VALUE</H2><PRE>
601 These functions all return TRUE or FALSE, except as noted.
606 Both a macro and a function are provided for each name.
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.
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>
623 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
627 Man(1) output converted with
628 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>