2 ****************************************************************************
3 * Copyright 2021,2022 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.31 2022/02/12 20:05:11 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">
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>
61 <STRONG>int</STRONG> <STRONG>get_escdelay(void);</STRONG>
62 <STRONG>int</STRONG> <STRONG>set_escdelay(int</STRONG> <EM>ms</EM><STRONG>);</STRONG>
63 <STRONG>int</STRONG> <STRONG>set_tabsize(int</STRONG> <EM>cols</EM><STRONG>);</STRONG>
65 <STRONG>int</STRONG> <STRONG>use_screen(SCREEN</STRONG> <STRONG>*</STRONG><EM>scr</EM><STRONG>,</STRONG> <STRONG>NCURSES_SCREEN_CB</STRONG> <EM>func</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>data</EM><STRONG>);</STRONG>
66 <STRONG>int</STRONG> <STRONG>use_window(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>NCURSES_WINDOW_CB</STRONG> <EM>func</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>data</EM><STRONG>);</STRONG>
69 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
70 This implementation can be configured to provide rudimentary support
71 for multi-threaded applications. This makes a different set of li-
72 braries, e.g., <STRONG>libncursest</STRONG> since the binary interfaces are different.
74 Rather than modify the interfaces to pass a thread specifier to each
75 function, it adds a few functions which can be used in any configura-
76 tion which hide the mutex's needed to prevent concurrent use of the
77 global variables when configured for threading.
79 In addition to forcing access to members of the <STRONG>WINDOW</STRONG> structure to be
80 via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it makes functions of the common
81 global variables, e.g., COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES,
82 TABSIZE curscr, newscr and ttytype. Those variables are maintained as
83 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
85 Even this is not enough to make a thread-safe application using curses.
86 A multi-threaded application would be expected to have threads updating
87 separate windows (within the same device), or updating on separate
88 screens (on different devices). Also, a few of the global variables
89 are considered writable by some applications. The functions described
90 here address these special situations.
92 The ESCDELAY and TABSIZE global variables are modified by some applica-
93 tions. To modify them in any configuration, use the <STRONG>set_escdelay</STRONG> or
94 <STRONG>set_tabsize</STRONG> functions. Other global variables are not modifiable.
96 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
98 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse granularity mu-
99 texes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG> parameters, and call a us-
100 er-supplied function, passing it a <EM>data</EM> parameter, and returning the
101 value from the user-supplied function to the application.
104 </PRE><H3><a name="h3-USAGE">USAGE</a></H3><PRE>
105 All of the ncurses library functions assume that the locale is not al-
106 tered during operation. In addition, they use data which is maintained
107 within a hierarchy of scopes.
109 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo or termcap in-
112 <STRONG>o</STRONG> terminal data, e.g., associated with a call to <STRONG>set_curterm</STRONG>. The
113 terminal data are initialized when screens are created.
115 <STRONG>o</STRONG> screen data, e.g., associated with a call to <STRONG>newterm</STRONG> or <STRONG>initscr</STRONG>.
117 <STRONG>o</STRONG> window data, e.g., associated with a call to <STRONG>newwin</STRONG> or <STRONG>subwin</STRONG>.
118 Windows are associated with screens. Pads are not necessarily
119 associated with a particular screen.
121 Most curses applications operate on one or more windows within a
124 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as parameters.
126 This table lists the scope of data used for each symbol in the ncurses
127 library when it is configured to support threading:
130 -------------------------------------------------------------
132 COLORS screen (readonly)
134 COLOR_PAIRS screen (readonly)
135 COLS screen (readonly)
136 ESCDELAY screen (readonly, see <STRONG>set_escdelay</STRONG>)
137 LINES screen (readonly)
138 PAIR_NUMBER reentrant
141 TABSIZE screen (readonly)
143 acs_map screen (readonly)
144 add_wch window (stdscr)
145 add_wchnstr window (stdscr)
146 add_wchstr window (stdscr)
147 addch window (stdscr)
148 addchnstr window (stdscr)
149 addchstr window (stdscr)
150 addnstr window (stdscr)
151 addnwstr window (stdscr)
152 addstr window (stdscr)
153 addwstr window (stdscr)
154 assume_default_colors screen
155 attr_get window (stdscr)
156 attr_off window (stdscr)
157 attr_on window (stdscr)
158 attr_set window (stdscr)
159 attroff window (stdscr)
160 attron window (stdscr)
161 attrset window (stdscr)
165 bkgdset window (stdscr)
166 bkgrnd window (stdscr)
167 bkgrndset window (stdscr)
168 boolcodes global (readonly)
169 boolfnames global (readonly)
170 boolnames global (readonly)
171 border window (stdscr)
172 border_set window (stdscr)
174 box_set window (stdscr)
175 can_change_color terminal
177 chgat window (stdscr)
178 clear window (stdscr)
180 clrtobot window (stdscr)
181 clrtoeol window (stdscr)
184 color_set window (stdscr)
185 copywin window locks(source, target)
188 curscr screen (readonly)
189 curses_version global (readonly)
190 def_prog_mode terminal
191 def_shell_mode terminal
195 delch window (stdscr)
196 deleteln window (stdscr)
197 delscreen global locks(screenlist, screen)
198 delwin global locks(windowlist)
201 dupwin screen locks(window)
203 echo_wchar window (stdscr)
204 echochar window (stdscr)
206 erase window (stdscr)
207 erasechar window (stdscr)
208 erasewchar window (stdscr)
212 get_wch screen (input-operation)
213 get_wstr screen (input-operation)
220 getch screen (input-operation)
225 getmouse screen (input-operation)
226 getn_wstr screen (input-operation)
227 getnstr screen (input-operation)
230 getstr screen (input-operation)
231 getwin screen (input-operation)
237 hline window (stdscr)
238 hline_set window (stdscr)
242 in_wch window (stdscr)
243 in_wchnstr window (stdscr)
244 in_wchstr window (stdscr)
246 inchnstr window (stdscr)
247 inchstr window (stdscr)
251 initscr global locks(screenlist)
252 innstr window (stdscr)
253 innwstr window (stdscr)
254 ins_nwstr window (stdscr)
255 ins_wch window (stdscr)
256 ins_wstr window (stdscr)
257 insch window (stdscr)
258 insdelln window (stdscr)
259 insertln window (stdscr)
260 insnstr window (stdscr)
261 insstr window (stdscr)
262 instr window (stdscr)
264 inwstr window (stdscr)
271 is_linetouched window
276 is_term_resized terminal
280 key_name global (static data)
282 keyname global (static data)
291 mouse_trafo window (stdscr)
295 mvadd_wch window (stdscr)
296 mvadd_wchnstr window (stdscr)
297 mvadd_wchstr window (stdscr)
298 mvaddch window (stdscr)
299 mvaddchnstr window (stdscr)
300 mvaddchstr window (stdscr)
301 mvaddnstr window (stdscr)
302 mvaddnwstr window (stdscr)
303 mvaddstr window (stdscr)
304 mvaddwstr window (stdscr)
305 mvchgat window (stdscr)
307 mvdelch window (stdscr)
308 mvderwin window (stdscr)
309 mvget_wch screen (input-operation)
310 mvget_wstr screen (input-operation)
311 mvgetch screen (input-operation)
312 mvgetn_wstr screen (input-operation)
313 mvgetnstr screen (input-operation)
314 mvgetstr screen (input-operation)
315 mvhline window (stdscr)
316 mvhline_set window (stdscr)
318 mvin_wch window (stdscr)
319 mvin_wchnstr window (stdscr)
320 mvin_wchstr window (stdscr)
321 mvinch window (stdscr)
322 mvinchnstr window (stdscr)
323 mvinchstr window (stdscr)
324 mvinnstr window (stdscr)
325 mvinnwstr window (stdscr)
326 mvins_nwstr window (stdscr)
327 mvins_wch window (stdscr)
328 mvins_wstr window (stdscr)
329 mvinsch window (stdscr)
330 mvinsnstr window (stdscr)
331 mvinsstr window (stdscr)
332 mvinstr window (stdscr)
333 mvinwstr window (stdscr)
334 mvprintw window (stdscr)
336 mvvline window (stdscr)
337 mvvline_set window (stdscr)
339 mvwadd_wchnstr window
350 mvwget_wch screen (input-operation)
351 mvwget_wstr screen (input-operation)
352 mvwgetch screen (input-operation)
353 mvwgetn_wstr screen (input-operation)
354 mvwgetnstr screen (input-operation)
355 mvwgetstr screen (input-operation)
380 newpad global locks(windowlist)
381 newscr screen (readonly)
382 newterm global locks(screenlist)
383 newwin global locks(windowlist)
394 numcodes global (readonly)
395 numfnames global (readonly)
396 numnames global (readonly)
398 overlay window locks(source, target)
399 overwrite window locks(source, target)
412 reset_prog_mode screen
413 reset_shell_mode screen
415 resize_term screen locks(windowlist)
418 ripoffline global (static data)
431 set_term global locks(screenlist, screen)
433 setscrreg window (stdscr)
446 slk_noutrefresh screen
456 stdscr screen (readonly)
457 strcodes global (readonly)
458 strfnames global (readonly)
459 strnames global (readonly)
474 timeout window (stdscr)
477 tparm global (static data)
479 trace global (static data)
480 ttytype screen (readonly)
483 unget_wch screen (input-operation)
484 ungetch screen (input-operation)
485 ungetmouse screen (input-operation)
487 use_default_colors screen
488 use_env global (static data)
489 use_extended_names global (static data)
490 use_legacy_coding screen
491 use_screen global locks(screenlist, screen)
492 use_window global locks(windowlist, window)
497 vline window (stdscr)
498 vline_set window (stdscr)
532 wcursyncup screen (affects window plus parents)
539 wget_wch screen (input-operation)
540 wget_wstr screen (input-operation)
542 wgetch screen (input-operation)
544 wgetn_wstr screen (input-operation)
545 wgetnstr screen (input-operation)
548 wgetstr screen (input-operation)
575 wresize window locks(windowlist)
581 wsyncdown screen (affects window plus parents)
582 wsyncup screen (affects window plus parents)
586 wunctrl global (static data)
591 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
592 These functions all return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, except as noted.
595 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
596 Both a macro and a function are provided for each name.
599 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
600 These routines are specific to ncurses. They were not supported on
601 Version 7, BSD or System V implementations. It is recommended that any
602 code depending on ncurses extensions be conditioned using NCURSES_VER-
606 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
607 <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>.
611 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
615 <li><a href="#h2-NAME">NAME</a></li>
616 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
617 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
619 <li><a href="#h3-USAGE">USAGE</a></li>
622 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
623 <li><a href="#h2-NOTES">NOTES</a></li>
624 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
625 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>