2 ****************************************************************************
3 * Copyright 2020 Thomas E. Dickey *
4 * Copyright 2008-2015,2017 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.25 2020/02/02 23:34:34 tom Exp @
31 * ***************************************************************************
32 * ***************************************************************************
34 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
37 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
38 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
39 <TITLE>curs_threads 3x</TITLE>
40 <link rel="author" href="mailto:bug-ncurses@gnu.org">
41 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
44 <H1 class="no-header">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>
51 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
52 <STRONG>curs_threads</STRONG> - <STRONG>curses</STRONG> thread support
55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
56 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
58 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_WINDOW_CB)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
59 <STRONG>typedef</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_SCREEN_CB)(SCREEN</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
60 <STRONG>int</STRONG> <STRONG>get_escdelay(void);</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_SCREEN_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG> <STRONG>*data);</STRONG>
64 <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>
67 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
68 This implementation can be configured to provide rudimentary support
69 for multi-threaded applications. This makes a different set of li-
70 braries, e.g., <EM>libncursest</EM> since the binary interfaces are different.
72 Rather than modify the interfaces to pass a thread specifier to each
73 function, it adds a few functions which can be used in any configura-
74 tion which hide the mutex's needed to prevent concurrent use of the
75 global variables when configured for threading.
77 In addition to forcing access to members of the <STRONG>WINDOW</STRONG> structure to be
78 via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it makes functions of the common
79 global variables, e.g., COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES,
80 TABSIZE curscr, newscr and ttytype. Those variables are maintained as
81 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
83 Even this is not enough to make a thread-safe application using curses.
84 A multi-threaded application would be expected to have threads updating
85 separate windows (within the same device), or updating on separate
86 screens (on different devices). Also, a few of the global variables
87 are considered writable by some applications. The functions described
88 here address these special situations.
90 The ESCDELAY and TABSIZE global variables are modified by some applica-
91 tions. To modify them in any configuration, use the <STRONG>set_escdelay</STRONG> or
92 <STRONG>set_tabsize</STRONG> functions. Other global variables are not modifiable.
94 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
96 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse granularity mu-
97 texes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG> parameters, and call a us-
98 er-supplied function, passing it a <EM>data</EM> parameter, and returning the
99 value from the user-supplied function to the application.
102 </PRE><H3><a name="h3-USAGE">USAGE</a></H3><PRE>
103 All of the ncurses library functions assume that the locale is not al-
104 tered during operation. In addition, they use data which is maintained
105 within a hierarchy of scopes.
107 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo or termcap in-
110 <STRONG>o</STRONG> terminal data, e.g., associated with a call to <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. The
111 terminal data are initialized when screens are created.
113 <STRONG>o</STRONG> screen data, e.g., associated with a call to <EM>newterm</EM> or <EM>initscr</EM>.
115 <STRONG>o</STRONG> window data, e.g., associated with a call to <EM>newwin</EM> or <EM>subwin</EM>.
116 Windows are associated with screens. Pads are not necessarily
117 associated with a particular screen.
119 Most curses applications operate on one or more windows within a
122 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as parameters.
124 This table lists the scope of data used for each symbol in the ncurses
125 library when it is configured to support threading:
128 -------------------------------------------------------------
130 COLORS screen (readonly)
132 COLOR_PAIRS screen (readonly)
133 COLS screen (readonly)
134 ESCDELAY screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
135 LINES screen (readonly)
136 PAIR_NUMBER reentrant
139 TABSIZE screen (readonly)
141 acs_map screen (readonly)
142 add_wch window (stdscr)
143 add_wchnstr window (stdscr)
144 add_wchstr window (stdscr)
145 addch window (stdscr)
146 addchnstr window (stdscr)
147 addchstr window (stdscr)
148 addnstr window (stdscr)
149 addnwstr window (stdscr)
150 addstr window (stdscr)
151 addwstr window (stdscr)
152 assume_default_colors screen
153 attr_get window (stdscr)
154 attr_off window (stdscr)
155 attr_on window (stdscr)
156 attr_set window (stdscr)
157 attroff window (stdscr)
158 attron window (stdscr)
159 attrset window (stdscr)
163 bkgdset window (stdscr)
164 bkgrnd window (stdscr)
165 bkgrndset window (stdscr)
166 boolcodes global (readonly)
167 boolfnames global (readonly)
168 boolnames global (readonly)
169 border window (stdscr)
170 border_set window (stdscr)
172 box_set window (stdscr)
173 can_change_color terminal
175 chgat window (stdscr)
176 clear window (stdscr)
178 clrtobot window (stdscr)
179 clrtoeol window (stdscr)
181 color_set window (stdscr)
182 copywin window locks(source, target)
186 curscr screen (readonly)
187 curses_version global (readonly)
188 def_prog_mode terminal
189 def_shell_mode terminal
193 delch window (stdscr)
194 deleteln window (stdscr)
195 delscreen global locks(screenlist, screen)
196 delwin global locks(windowlist)
199 dupwin screen locks(window)
201 echo_wchar window (stdscr)
202 echochar window (stdscr)
204 erase window (stdscr)
205 erasechar window (stdscr)
206 erasewchar window (stdscr)
210 get_wch screen (input-operation)
211 get_wstr screen (input-operation)
218 getch screen (input-operation)
223 getmouse screen (input-operation)
224 getn_wstr screen (input-operation)
225 getnstr screen (input-operation)
228 getstr screen (input-operation)
229 getwin screen (input-operation)
235 hline window (stdscr)
236 hline_set window (stdscr)
240 in_wch window (stdscr)
241 in_wchnstr window (stdscr)
242 in_wchstr window (stdscr)
244 inchnstr window (stdscr)
245 inchstr window (stdscr)
248 initscr global locks(screenlist)
249 innstr window (stdscr)
251 innwstr window (stdscr)
252 ins_nwstr window (stdscr)
253 ins_wch window (stdscr)
254 ins_wstr window (stdscr)
255 insch window (stdscr)
256 insdelln window (stdscr)
257 insertln window (stdscr)
258 insnstr window (stdscr)
259 insstr window (stdscr)
260 instr window (stdscr)
262 inwstr window (stdscr)
269 is_linetouched window
274 is_term_resized terminal
278 key_name global (static data)
280 keyname global (static data)
289 mouse_trafo window (stdscr)
293 mvadd_wch window (stdscr)
294 mvadd_wchnstr window (stdscr)
295 mvadd_wchstr window (stdscr)
296 mvaddch window (stdscr)
297 mvaddchnstr window (stdscr)
298 mvaddchstr window (stdscr)
299 mvaddnstr window (stdscr)
300 mvaddnwstr window (stdscr)
301 mvaddstr window (stdscr)
302 mvaddwstr window (stdscr)
303 mvchgat window (stdscr)
305 mvdelch window (stdscr)
306 mvderwin window (stdscr)
307 mvget_wch screen (input-operation)
308 mvget_wstr screen (input-operation)
309 mvgetch screen (input-operation)
310 mvgetn_wstr screen (input-operation)
311 mvgetnstr screen (input-operation)
312 mvgetstr screen (input-operation)
313 mvhline window (stdscr)
314 mvhline_set window (stdscr)
315 mvin_wch window (stdscr)
316 mvin_wchnstr window (stdscr)
318 mvin_wchstr window (stdscr)
319 mvinch window (stdscr)
320 mvinchnstr window (stdscr)
321 mvinchstr window (stdscr)
322 mvinnstr window (stdscr)
323 mvinnwstr window (stdscr)
324 mvins_nwstr window (stdscr)
325 mvins_wch window (stdscr)
326 mvins_wstr window (stdscr)
327 mvinsch window (stdscr)
328 mvinsnstr window (stdscr)
329 mvinsstr window (stdscr)
330 mvinstr window (stdscr)
331 mvinwstr window (stdscr)
332 mvprintw window (stdscr)
334 mvvline window (stdscr)
335 mvvline_set window (stdscr)
337 mvwadd_wchnstr window
348 mvwget_wch screen (input-operation)
349 mvwget_wstr screen (input-operation)
350 mvwgetch screen (input-operation)
351 mvwgetn_wstr screen (input-operation)
352 mvwgetnstr screen (input-operation)
353 mvwgetstr screen (input-operation)
378 newpad global locks(windowlist)
379 newscr screen (readonly)
380 newterm global locks(screenlist)
381 newwin global locks(windowlist)
392 numcodes global (readonly)
393 numfnames global (readonly)
394 numnames global (readonly)
396 overlay window locks(source, target)
397 overwrite window locks(source, target)
410 reset_prog_mode screen
411 reset_shell_mode screen
413 resize_term screen locks(windowlist)
416 ripoffline global (static data)
429 set_term global locks(screenlist, screen)
431 setscrreg window (stdscr)
444 slk_noutrefresh screen
454 stdscr screen (readonly)
455 strcodes global (readonly)
456 strfnames global (readonly)
457 strnames global (readonly)
472 timeout window (stdscr)
475 tparm global (static data)
477 trace global (static data)
478 ttytype screen (readonly)
481 unget_wch screen (input-operation)
482 ungetch screen (input-operation)
483 ungetmouse screen (input-operation)
485 use_default_colors screen
486 use_env global (static data)
487 use_extended_names global (static data)
488 use_legacy_coding screen
489 use_screen global locks(screenlist, screen)
490 use_window global locks(windowlist, window)
495 vline window (stdscr)
496 vline_set window (stdscr)
530 wcursyncup screen (affects window plus parents)
537 wget_wch screen (input-operation)
538 wget_wstr screen (input-operation)
540 wgetch screen (input-operation)
542 wgetn_wstr screen (input-operation)
543 wgetnstr screen (input-operation)
546 wgetstr screen (input-operation)
573 wresize window locks(windowlist)
579 wsyncdown screen (affects window plus parents)
580 wsyncup screen (affects window plus parents)
583 wunctrl global (static data)
589 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
590 These functions all return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, except as noted.
593 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
594 Both a macro and a function are provided for each name.
597 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
598 These routines are specific to ncurses. They were not supported on
599 Version 7, BSD or System V implementations. It is recommended that any
600 code depending on ncurses extensions be conditioned using NCURSES_VER-
604 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
605 <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>.
609 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
613 <li><a href="#h2-NAME">NAME</a></li>
614 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
615 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
617 <li><a href="#h3-USAGE">USAGE</a></li>
620 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
621 <li><a href="#h2-NOTES">NOTES</a></li>
622 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
623 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>