2 ****************************************************************************
3 * Copyright (c) 2008-2015,2017 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.24 2017/11/18 23:56:00 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 https://invisible-island.net/scripts/readme.html#others_scripts">
38 <TITLE>curs_threads 3x</TITLE>
39 <link rel="author" 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>
50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
51 <STRONG>curs_threads</STRONG> - <STRONG>curses</STRONG> thread support
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
57 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_WINDOW_CB)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
58 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_SCREEN_CB)(SCREEN</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
59 <STRONG>int</STRONG> <STRONG>get_escdelay(void);</STRONG>
60 <STRONG>int</STRONG> <STRONG>set_escdelay(int</STRONG> <STRONG>size);</STRONG>
61 <STRONG>int</STRONG> <STRONG>set_tabsize(int</STRONG> <STRONG>size);</STRONG>
62 <STRONG>int</STRONG> <STRONG>use_screen(SCREEN</STRONG> <STRONG>*scr,</STRONG> <STRONG>NCURSES_SCREEN_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG> <STRONG>*data);</STRONG>
63 <STRONG>int</STRONG> <STRONG>use_window(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>NCURSES_WINDOW_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG> <STRONG>*data);</STRONG>
66 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
67 This implementation can be configured to provide rudimentary support
68 for multi-threaded applications. This makes a different set of li-
69 braries, e.g., <EM>libncursest</EM> since the binary interfaces are different.
71 Rather than modify the interfaces to pass a thread specifier to each
72 function, it adds a few functions which can be used in any configura-
73 tion which hide the mutex's needed to prevent concurrent use of the
74 global variables when configured for threading.
76 In addition to forcing access to members of the <STRONG>WINDOW</STRONG> structure to be
77 via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it makes functions of the common
78 global variables, e.g., COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES,
79 TABSIZE curscr, newscr and ttytype. Those variables are maintained as
80 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
82 Even this is not enough to make a thread-safe application using curses.
83 A multi-threaded application would be expected to have threads updating
84 separate windows (within the same device), or updating on separate
85 screens (on different devices). Also, a few of the global variables
86 are considered writable by some applications. The functions described
87 here address these special situations.
89 The ESCDELAY and TABSIZE global variables are modified by some applica-
90 tions. To modify them in any configuration, use the <STRONG>set_escdelay</STRONG> or
91 <STRONG>set_tabsize</STRONG> functions. Other global variables are not modifiable.
93 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
95 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse granularity mu-
96 texes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG> parameters, and call a us-
97 er-supplied function, passing it a <EM>data</EM> parameter, and returning the
98 value from the user-supplied function to the application.
101 </PRE><H3><a name="h3-USAGE">USAGE</a></H3><PRE>
102 All of the ncurses library functions assume that the locale is not al-
103 tered during operation. In addition, they use data which is maintained
104 within a hierarchy of scopes.
106 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo or termcap in-
109 <STRONG>o</STRONG> terminal data, e.g., associated with a call to <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. The
110 terminal data are initialized when screens are created.
112 <STRONG>o</STRONG> screen data, e.g., associated with a call to <EM>newterm</EM> or <EM>initscr</EM>.
114 <STRONG>o</STRONG> window data, e.g., associated with a call to <EM>newwin</EM> or <EM>subwin</EM>.
115 Windows are associated with screens. Pads are not necessarily
116 associated with a particular screen.
118 Most curses applications operate on one or more windows within a
121 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as parameters.
123 This table lists the scope of data used for each symbol in the ncurses
124 library when it is configured to support threading:
127 -------------------------------------------------------------
129 COLORS screen (readonly)
131 COLOR_PAIRS screen (readonly)
132 COLS screen (readonly)
133 ESCDELAY screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
134 LINES screen (readonly)
135 PAIR_NUMBER reentrant
138 TABSIZE screen (readonly)
140 acs_map screen (readonly)
141 add_wch window (stdscr)
142 add_wchnstr window (stdscr)
143 add_wchstr window (stdscr)
144 addch window (stdscr)
145 addchnstr window (stdscr)
146 addchstr window (stdscr)
147 addnstr window (stdscr)
148 addnwstr window (stdscr)
149 addstr window (stdscr)
150 addwstr window (stdscr)
151 assume_default_colors screen
152 attr_get window (stdscr)
153 attr_off window (stdscr)
154 attr_on window (stdscr)
155 attr_set window (stdscr)
156 attroff window (stdscr)
157 attron window (stdscr)
158 attrset window (stdscr)
162 bkgdset window (stdscr)
163 bkgrnd window (stdscr)
164 bkgrndset window (stdscr)
165 boolcodes global (readonly)
166 boolfnames global (readonly)
167 boolnames global (readonly)
168 border window (stdscr)
169 border_set window (stdscr)
171 box_set window (stdscr)
172 can_change_color terminal
174 chgat window (stdscr)
175 clear window (stdscr)
177 clrtobot window (stdscr)
178 clrtoeol window (stdscr)
180 color_set window (stdscr)
181 copywin window locks(source, target)
185 curscr screen (readonly)
186 curses_version global (readonly)
187 def_prog_mode terminal
188 def_shell_mode terminal
192 delch window (stdscr)
193 deleteln window (stdscr)
194 delscreen global locks(screenlist, screen)
195 delwin global locks(windowlist)
198 dupwin screen locks(window)
200 echo_wchar window (stdscr)
201 echochar window (stdscr)
203 erase window (stdscr)
204 erasechar window (stdscr)
205 erasewchar window (stdscr)
209 get_wch screen (input-operation)
210 get_wstr screen (input-operation)
217 getch screen (input-operation)
222 getmouse screen (input-operation)
223 getn_wstr screen (input-operation)
224 getnstr screen (input-operation)
227 getstr screen (input-operation)
228 getwin screen (input-operation)
234 hline window (stdscr)
235 hline_set window (stdscr)
239 in_wch window (stdscr)
240 in_wchnstr window (stdscr)
241 in_wchstr window (stdscr)
243 inchnstr window (stdscr)
244 inchstr window (stdscr)
247 initscr global locks(screenlist)
248 innstr window (stdscr)
250 innwstr window (stdscr)
251 ins_nwstr window (stdscr)
252 ins_wch window (stdscr)
253 ins_wstr window (stdscr)
254 insch window (stdscr)
255 insdelln window (stdscr)
256 insertln window (stdscr)
257 insnstr window (stdscr)
258 insstr window (stdscr)
259 instr window (stdscr)
261 inwstr window (stdscr)
268 is_linetouched window
273 is_term_resized terminal
277 key_name global (static data)
279 keyname global (static data)
288 mouse_trafo window (stdscr)
292 mvadd_wch window (stdscr)
293 mvadd_wchnstr window (stdscr)
294 mvadd_wchstr window (stdscr)
295 mvaddch window (stdscr)
296 mvaddchnstr window (stdscr)
297 mvaddchstr window (stdscr)
298 mvaddnstr window (stdscr)
299 mvaddnwstr window (stdscr)
300 mvaddstr window (stdscr)
301 mvaddwstr window (stdscr)
302 mvchgat window (stdscr)
304 mvdelch window (stdscr)
305 mvderwin window (stdscr)
306 mvget_wch screen (input-operation)
307 mvget_wstr screen (input-operation)
308 mvgetch screen (input-operation)
309 mvgetn_wstr screen (input-operation)
310 mvgetnstr screen (input-operation)
311 mvgetstr screen (input-operation)
312 mvhline window (stdscr)
313 mvhline_set window (stdscr)
314 mvin_wch window (stdscr)
315 mvin_wchnstr window (stdscr)
317 mvin_wchstr window (stdscr)
318 mvinch window (stdscr)
319 mvinchnstr window (stdscr)
320 mvinchstr window (stdscr)
321 mvinnstr window (stdscr)
322 mvinnwstr window (stdscr)
323 mvins_nwstr window (stdscr)
324 mvins_wch window (stdscr)
325 mvins_wstr window (stdscr)
326 mvinsch window (stdscr)
327 mvinsnstr window (stdscr)
328 mvinsstr window (stdscr)
329 mvinstr window (stdscr)
330 mvinwstr window (stdscr)
331 mvprintw window (stdscr)
333 mvvline window (stdscr)
334 mvvline_set window (stdscr)
336 mvwadd_wchnstr window
347 mvwget_wch screen (input-operation)
348 mvwget_wstr screen (input-operation)
349 mvwgetch screen (input-operation)
350 mvwgetn_wstr screen (input-operation)
351 mvwgetnstr screen (input-operation)
352 mvwgetstr screen (input-operation)
377 newpad global locks(windowlist)
378 newscr screen (readonly)
379 newterm global locks(screenlist)
380 newwin global locks(windowlist)
391 numcodes global (readonly)
392 numfnames global (readonly)
393 numnames global (readonly)
395 overlay window locks(source, target)
396 overwrite window locks(source, target)
409 reset_prog_mode screen
410 reset_shell_mode screen
412 resize_term screen locks(windowlist)
415 ripoffline global (static data)
428 set_term global locks(screenlist, screen)
430 setscrreg window (stdscr)
443 slk_noutrefresh screen
453 stdscr screen (readonly)
454 strcodes global (readonly)
455 strfnames global (readonly)
456 strnames global (readonly)
471 timeout window (stdscr)
474 tparm global (static data)
476 trace global (static data)
477 ttytype screen (readonly)
480 unget_wch screen (input-operation)
481 ungetch screen (input-operation)
482 ungetmouse screen (input-operation)
484 use_default_colors screen
485 use_env global (static data)
486 use_extended_names global (static data)
487 use_legacy_coding screen
488 use_screen global locks(screenlist, screen)
489 use_window global locks(windowlist, window)
494 vline window (stdscr)
495 vline_set window (stdscr)
529 wcursyncup screen (affects window plus parents)
536 wget_wch screen (input-operation)
537 wget_wstr screen (input-operation)
539 wgetch screen (input-operation)
541 wgetn_wstr screen (input-operation)
542 wgetnstr screen (input-operation)
545 wgetstr screen (input-operation)
572 wresize window locks(windowlist)
578 wsyncdown screen (affects window plus parents)
579 wsyncup screen (affects window plus parents)
582 wunctrl global (static data)
588 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
589 These functions all return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, except as noted.
592 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
593 Both a macro and a function are provided for each name.
596 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
597 These routines are specific to ncurses. They were not supported on
598 Version 7, BSD or System V implementations. It is recommended that any
599 code depending on ncurses extensions be conditioned using NCURSES_VER-
603 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
604 <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>.
608 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
612 <li><a href="#h2-NAME">NAME</a></li>
613 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
614 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
616 <li><a href="#h3-USAGE">USAGE</a></li>
619 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
620 <li><a href="#h2-NOTES">NOTES</a></li>
621 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
622 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>