2 ****************************************************************************
3 * Copyright (c) 2008-2014,2015 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.21 2015/04/11 10:23:49 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 class="no-header">curs_threads 3x</H1>
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>
51 <H2><a name="h2-NAME">NAME</a></H2><PRE>
52 <STRONG>use_screen</STRONG>, <STRONG>use_window</STRONG> - <STRONG>curses</STRONG> thread support
56 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></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><a name="h2-DESCRIPTION">DESCRIPTION</a></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.
113 <H3><a name="h3-USAGE">USAGE</a></H3><PRE>
114 All of the ncurses library functions assume that the lo-
115 cale is not altered during operation. In addition, they
116 use data which is maintained within a hierarchy of scopes.
118 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo
119 or termcap interfaces.
121 <STRONG>o</STRONG> terminal data, e.g., associated with a call to
122 <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. The terminal data are initialized
123 when screens are created.
125 <STRONG>o</STRONG> screen data, e.g., associated with a call to
126 <EM>newterm</EM> or <EM>initscr</EM>.
128 <STRONG>o</STRONG> window data, e.g., associated with a call to <EM>newwin</EM>
129 or <EM>subwin</EM>. Windows are associated with screens.
130 Pads are not necessarily associated with a particu-
133 Most curses applications operate on one or more
134 windows within a single screen.
136 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as
139 This table lists the scope of data used for each symbol in
140 the ncurses library when it is configured to support
144 -------------------------------------------------------------
146 COLORS screen (readonly)
148 COLOR_PAIRS screen (readonly)
149 COLS screen (readonly)
150 ESCDELAY screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
151 LINES screen (readonly)
152 PAIR_NUMBER reentrant
155 TABSIZE screen (readonly)
157 acs_map screen (readonly)
158 add_wch window (stdscr)
159 add_wchnstr window (stdscr)
160 add_wchstr window (stdscr)
161 addch window (stdscr)
162 addchnstr window (stdscr)
163 addchstr window (stdscr)
164 addnstr window (stdscr)
165 addnwstr window (stdscr)
166 addstr window (stdscr)
167 addwstr window (stdscr)
168 assume_default_colors screen
169 attr_get window (stdscr)
170 attr_off window (stdscr)
171 attr_on window (stdscr)
172 attr_set window (stdscr)
173 attroff window (stdscr)
174 attron window (stdscr)
175 attrset window (stdscr)
179 bkgdset window (stdscr)
180 bkgrnd window (stdscr)
181 bkgrndset window (stdscr)
182 boolcodes global (readonly)
183 boolfnames global (readonly)
184 boolnames global (readonly)
185 border window (stdscr)
187 border_set window (stdscr)
189 box_set window (stdscr)
190 can_change_color terminal
192 chgat window (stdscr)
193 clear window (stdscr)
195 clrtobot window (stdscr)
196 clrtoeol window (stdscr)
198 color_set window (stdscr)
199 copywin window locks(source, target)
202 curscr screen (readonly)
203 curses_version global (readonly)
204 def_prog_mode terminal
205 def_shell_mode terminal
209 delch window (stdscr)
210 deleteln window (stdscr)
211 delscreen global locks(screenlist, screen)
212 delwin global locks(windowlist)
215 dupwin screen locks(window)
217 echo_wchar window (stdscr)
218 echochar window (stdscr)
220 erase window (stdscr)
221 erasechar window (stdscr)
222 erasewchar window (stdscr)
226 get_wch screen (input-operation)
227 get_wstr screen (input-operation)
234 getch screen (input-operation)
239 getmouse screen (input-operation)
240 getn_wstr screen (input-operation)
241 getnstr screen (input-operation)
244 getstr screen (input-operation)
245 getwin screen (input-operation)
251 hline window (stdscr)
252 hline_set window (stdscr)
257 in_wch window (stdscr)
258 in_wchnstr window (stdscr)
259 in_wchstr window (stdscr)
261 inchnstr window (stdscr)
262 inchstr window (stdscr)
265 initscr global locks(screenlist)
266 innstr window (stdscr)
267 innwstr window (stdscr)
268 ins_nwstr window (stdscr)
269 ins_wch window (stdscr)
270 ins_wstr window (stdscr)
271 insch window (stdscr)
272 insdelln window (stdscr)
273 insertln window (stdscr)
274 insnstr window (stdscr)
275 insstr window (stdscr)
276 instr window (stdscr)
278 inwstr window (stdscr)
285 is_linetouched window
290 is_term_resized terminal
294 key_name global (static data)
296 keyname global (static data)
305 mouse_trafo window (stdscr)
309 mvadd_wch window (stdscr)
310 mvadd_wchnstr window (stdscr)
311 mvadd_wchstr window (stdscr)
312 mvaddch window (stdscr)
313 mvaddchnstr window (stdscr)
314 mvaddchstr window (stdscr)
315 mvaddnstr window (stdscr)
316 mvaddnwstr window (stdscr)
317 mvaddstr window (stdscr)
318 mvaddwstr window (stdscr)
319 mvchgat window (stdscr)
322 mvdelch window (stdscr)
323 mvderwin window (stdscr)
324 mvget_wch screen (input-operation)
325 mvget_wstr screen (input-operation)
326 mvgetch screen (input-operation)
327 mvgetn_wstr screen (input-operation)
328 mvgetnstr screen (input-operation)
329 mvgetstr screen (input-operation)
330 mvhline window (stdscr)
331 mvhline_set window (stdscr)
332 mvin_wch window (stdscr)
333 mvin_wchnstr window (stdscr)
334 mvin_wchstr window (stdscr)
335 mvinch window (stdscr)
336 mvinchnstr window (stdscr)
337 mvinchstr window (stdscr)
338 mvinnstr window (stdscr)
339 mvinnwstr window (stdscr)
340 mvins_nwstr window (stdscr)
341 mvins_wch window (stdscr)
342 mvins_wstr window (stdscr)
343 mvinsch window (stdscr)
344 mvinsnstr window (stdscr)
345 mvinsstr window (stdscr)
346 mvinstr window (stdscr)
347 mvinwstr window (stdscr)
348 mvprintw window (stdscr)
350 mvvline window (stdscr)
351 mvvline_set window (stdscr)
353 mvwadd_wchnstr window
364 mvwget_wch screen (input-operation)
365 mvwget_wstr screen (input-operation)
366 mvwgetch screen (input-operation)
367 mvwgetn_wstr screen (input-operation)
368 mvwgetnstr screen (input-operation)
369 mvwgetstr screen (input-operation)
395 newpad global locks(windowlist)
396 newscr screen (readonly)
397 newterm global locks(screenlist)
398 newwin global locks(windowlist)
408 numcodes global (readonly)
409 numfnames global (readonly)
410 numnames global (readonly)
412 overlay window locks(source, target)
413 overwrite window locks(source, target)
426 reset_prog_mode screen
427 reset_shell_mode screen
429 resize_term screen locks(windowlist)
432 ripoffline global (static data)
445 set_term global locks(screenlist, screen)
447 setscrreg window (stdscr)
461 slk_noutrefresh screen
470 stdscr screen (readonly)
471 strcodes global (readonly)
472 strfnames global (readonly)
473 strnames global (readonly)
488 timeout window (stdscr)
491 tparm global (static data)
493 trace global (static data)
494 ttytype screen (readonly)
497 unget_wch screen (input-operation)
498 ungetch screen (input-operation)
499 ungetmouse screen (input-operation)
501 use_default_colors screen
502 use_env global (static data)
503 use_extended_names global (static data)
504 use_legacy_coding screen
505 use_screen global locks(screenlist, screen)
506 use_window global locks(windowlist, window)
511 vline window (stdscr)
512 vline_set window (stdscr)
546 wcursyncup screen (affects window plus parents)
553 wget_wch screen (input-operation)
554 wget_wstr screen (input-operation)
556 wgetch screen (input-operation)
558 wgetn_wstr screen (input-operation)
559 wgetnstr screen (input-operation)
562 wgetstr screen (input-operation)
590 wresize window locks(windowlist)
596 wsyncdown screen (affects window plus parents)
597 wsyncup screen (affects window plus parents)
600 wunctrl global (static data)
606 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
607 These functions all return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, except as noted.
611 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
612 Both a macro and a function are provided for each name.
616 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
617 These routines are specific to ncurses. They were not
618 supported on Version 7, BSD or System V implementations.
619 It is recommended that any code depending on ncurses ex-
620 tensions be conditioned using NCURSES_VERSION.
624 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
625 <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>.
629 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
633 <li><a href="#h2-NAME">NAME</a></li>
634 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
635 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
637 <li><a href="#h3-USAGE">USAGE</a></li>
640 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
641 <li><a href="#h2-NOTES">NOTES</a></li>
642 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
643 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>