3 ****************************************************************************
4 * Copyright 2021-2022,2023 Thomas E. Dickey *
5 * Copyright 2008-2015,2017 Free Software Foundation, Inc. *
7 * Permission is hereby granted, free of charge, to any person obtaining a *
8 * copy of this software and associated documentation files (the *
9 * "Software"), to deal in the Software without restriction, including *
10 * without limitation the rights to use, copy, modify, merge, publish, *
11 * distribute, distribute with modifications, sublicense, and/or sell *
12 * copies of the Software, and to permit persons to whom the Software is *
13 * furnished to do so, subject to the following conditions: *
15 * The above copyright notice and this permission notice shall be included *
16 * in all copies or substantial portions of the Software. *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
21 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
22 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
23 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
24 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
26 * Except as contained in this notice, the name(s) of the above copyright *
27 * holders shall not be used in advertising or otherwise to promote the *
28 * sale, use or other dealings in this Software without prior written *
30 ****************************************************************************
31 * @Id: curs_threads.3x,v 1.36 2023/08/06 00:02:33 tom Exp @
32 * ***************************************************************************
33 * ***************************************************************************
35 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
38 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
39 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
40 <TITLE>curs_threads 3x 2023-08-05 ncurses 6.4 Library calls</TITLE>
41 <link rel="author" href="mailto:bug-ncurses@gnu.org">
45 <H1 class="no-header">curs_threads 3x 2023-08-05 ncurses 6.4 Library calls</H1>
47 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
52 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
53 <STRONG>curs_threads</STRONG> - <STRONG>curses</STRONG> thread support
56 </PRE><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>
62 <STRONG>int</STRONG> <STRONG>get_escdelay(void);</STRONG>
63 <STRONG>int</STRONG> <STRONG>set_escdelay(int</STRONG> <EM>ms</EM><STRONG>);</STRONG>
64 <STRONG>int</STRONG> <STRONG>set_tabsize(int</STRONG> <EM>cols</EM><STRONG>);</STRONG>
66 <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>
67 <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>
70 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
71 This implementation can be configured to provide rudimentary support
72 for multi-threaded applications. This makes a different set of li-
73 braries, e.g., <STRONG>libncursest</STRONG> since the binary interfaces are different.
75 Rather than modify the interfaces to pass a thread specifier to each
76 function, it adds a few functions which can be used in any configura-
77 tion which hide the mutex's needed to prevent concurrent use of the
78 global variables when configured for threading.
80 In addition to forcing access to members of the <STRONG>WINDOW</STRONG> structure to be
81 via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it makes functions of the common
82 global variables, e.g., COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES,
83 TABSIZE curscr, newscr and ttytype. Those variables are maintained as
84 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
86 Even this is not enough to make a thread-safe application using curses.
87 A multi-threaded application would be expected to have threads updating
88 separate windows (within the same device), or updating on separate
89 screens (on different devices). Also, a few of the global variables
90 are considered writable by some applications. The functions described
91 here address these special situations.
93 The ESCDELAY and TABSIZE global variables are modified by some applica-
94 tions. To modify them in any configuration, use the <STRONG>set_escdelay</STRONG> or
95 <STRONG>set_tabsize</STRONG> functions. Other global variables are not modifiable.
97 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
99 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse granularity mu-
100 texes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG> parameters, and call a us-
101 er-supplied function, passing it a <EM>data</EM> parameter, and returning the
102 value from the user-supplied function to the application.
105 </PRE><H3><a name="h3-USAGE">USAGE</a></H3><PRE>
106 All of the ncurses library functions assume that the locale is not al-
107 tered during operation. In addition, they use data which is maintained
108 within a hierarchy of scopes.
110 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo or termcap in-
113 <STRONG>o</STRONG> terminal data, e.g., associated with a call to <STRONG>set_curterm</STRONG>. The
114 terminal data are initialized when screens are created.
116 <STRONG>o</STRONG> screen data, e.g., associated with a call to <STRONG>newterm</STRONG> or <STRONG>initscr</STRONG>.
118 <STRONG>o</STRONG> window data, e.g., associated with a call to <STRONG>newwin</STRONG> or <STRONG>subwin</STRONG>.
119 Windows are associated with screens. Pads are not necessarily
120 associated with a particular screen.
122 Most curses applications operate on one or more windows within a
125 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as parameters.
127 This table lists the scope of data used for each symbol in the ncurses
128 library when it is configured to support threading:
131 -------------------------------------------------------------
133 COLORS screen (readonly)
135 COLOR_PAIRS screen (readonly)
136 COLS screen (readonly)
137 ESCDELAY screen (readonly, see <STRONG>set_escdelay</STRONG>)
138 LINES screen (readonly)
139 PAIR_NUMBER reentrant
142 TABSIZE screen (readonly)
144 acs_map screen (readonly)
145 add_wch window (stdscr)
146 add_wchnstr window (stdscr)
147 add_wchstr window (stdscr)
148 addch window (stdscr)
149 addchnstr window (stdscr)
150 addchstr window (stdscr)
151 addnstr window (stdscr)
152 addnwstr window (stdscr)
153 addstr window (stdscr)
154 addwstr window (stdscr)
155 assume_default_colors screen
156 attr_get window (stdscr)
157 attr_off window (stdscr)
158 attr_on window (stdscr)
159 attr_set window (stdscr)
160 attroff window (stdscr)
161 attron window (stdscr)
162 attrset window (stdscr)
166 bkgdset window (stdscr)
167 bkgrnd window (stdscr)
168 bkgrndset window (stdscr)
169 boolcodes global (readonly)
170 boolfnames global (readonly)
171 boolnames global (readonly)
172 border window (stdscr)
173 border_set window (stdscr)
175 box_set window (stdscr)
176 can_change_color terminal
178 chgat window (stdscr)
179 clear window (stdscr)
181 clrtobot window (stdscr)
182 clrtoeol window (stdscr)
185 color_set window (stdscr)
186 copywin window locks(source, target)
189 curscr screen (readonly)
190 curses_version global (readonly)
191 def_prog_mode terminal
192 def_shell_mode terminal
196 delch window (stdscr)
197 deleteln window (stdscr)
198 delscreen global locks(screenlist, screen)
199 delwin global locks(windowlist)
202 dupwin screen locks(window)
204 echo_wchar window (stdscr)
205 echochar window (stdscr)
207 erase window (stdscr)
208 erasechar window (stdscr)
209 erasewchar window (stdscr)
213 get_wch screen (input-operation)
214 get_wstr screen (input-operation)
221 getch screen (input-operation)
226 getmouse screen (input-operation)
227 getn_wstr screen (input-operation)
228 getnstr screen (input-operation)
231 getstr screen (input-operation)
232 getwin screen (input-operation)
238 hline window (stdscr)
239 hline_set window (stdscr)
243 in_wch window (stdscr)
244 in_wchnstr window (stdscr)
245 in_wchstr window (stdscr)
247 inchnstr window (stdscr)
248 inchstr window (stdscr)
252 initscr global locks(screenlist)
253 innstr window (stdscr)
254 innwstr window (stdscr)
255 ins_nwstr window (stdscr)
256 ins_wch window (stdscr)
257 ins_wstr window (stdscr)
258 insch window (stdscr)
259 insdelln window (stdscr)
260 insertln window (stdscr)
261 insnstr window (stdscr)
262 insstr window (stdscr)
263 instr window (stdscr)
265 inwstr window (stdscr)
272 is_linetouched window
277 is_term_resized terminal
281 key_name global (static data)
283 keyname global (static data)
292 mouse_trafo window (stdscr)
296 mvadd_wch window (stdscr)
297 mvadd_wchnstr window (stdscr)
298 mvadd_wchstr window (stdscr)
299 mvaddch window (stdscr)
300 mvaddchnstr window (stdscr)
301 mvaddchstr window (stdscr)
302 mvaddnstr window (stdscr)
303 mvaddnwstr window (stdscr)
304 mvaddstr window (stdscr)
305 mvaddwstr window (stdscr)
306 mvchgat window (stdscr)
308 mvdelch window (stdscr)
309 mvderwin window (stdscr)
310 mvget_wch screen (input-operation)
311 mvget_wstr screen (input-operation)
312 mvgetch screen (input-operation)
313 mvgetn_wstr screen (input-operation)
314 mvgetnstr screen (input-operation)
315 mvgetstr screen (input-operation)
316 mvhline window (stdscr)
317 mvhline_set window (stdscr)
319 mvin_wch window (stdscr)
320 mvin_wchnstr window (stdscr)
321 mvin_wchstr window (stdscr)
322 mvinch window (stdscr)
323 mvinchnstr window (stdscr)
324 mvinchstr window (stdscr)
325 mvinnstr window (stdscr)
326 mvinnwstr window (stdscr)
327 mvins_nwstr window (stdscr)
328 mvins_wch window (stdscr)
329 mvins_wstr window (stdscr)
330 mvinsch window (stdscr)
331 mvinsnstr window (stdscr)
332 mvinsstr window (stdscr)
333 mvinstr window (stdscr)
334 mvinwstr window (stdscr)
335 mvprintw window (stdscr)
337 mvvline window (stdscr)
338 mvvline_set window (stdscr)
340 mvwadd_wchnstr window
351 mvwget_wch screen (input-operation)
352 mvwget_wstr screen (input-operation)
353 mvwgetch screen (input-operation)
354 mvwgetn_wstr screen (input-operation)
355 mvwgetnstr screen (input-operation)
356 mvwgetstr screen (input-operation)
381 newpad global locks(windowlist)
382 newscr screen (readonly)
383 newterm global locks(screenlist)
384 newwin global locks(windowlist)
395 numcodes global (readonly)
396 numfnames global (readonly)
397 numnames global (readonly)
399 overlay window locks(source, target)
400 overwrite window locks(source, target)
413 reset_prog_mode screen
414 reset_shell_mode screen
416 resize_term screen locks(windowlist)
419 ripoffline global (static data)
432 set_term global locks(screenlist, screen)
434 setscrreg window (stdscr)
447 slk_noutrefresh screen
457 stdscr screen (readonly)
458 strcodes global (readonly)
459 strfnames global (readonly)
460 strnames global (readonly)
475 timeout window (stdscr)
478 tparm global (static data)
480 trace global (static data)
481 ttytype screen (readonly)
484 unget_wch screen (input-operation)
485 ungetch screen (input-operation)
486 ungetmouse screen (input-operation)
488 use_default_colors screen
489 use_env global (static data)
490 use_extended_names global (static data)
491 use_legacy_coding screen
492 use_screen global locks(screenlist, screen)
493 use_window global locks(windowlist, window)
498 vline window (stdscr)
499 vline_set window (stdscr)
533 wcursyncup screen (affects window plus parents)
540 wget_wch screen (input-operation)
541 wget_wstr screen (input-operation)
543 wgetch screen (input-operation)
545 wgetn_wstr screen (input-operation)
546 wgetnstr screen (input-operation)
549 wgetstr screen (input-operation)
576 wresize window locks(windowlist)
582 wsyncdown screen (affects window plus parents)
583 wsyncup screen (affects window plus parents)
587 wunctrl global (static data)
592 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
593 These functions all return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, except as noted.
596 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
597 Both a macro and a function are provided for each name.
600 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
601 These routines are specific to ncurses. They were not supported on
602 Version 7, BSD or System V implementations. It is recommended that any
603 code depending on ncurses extensions be conditioned using NCURSES_VER-
607 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
608 <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>.
612 ncurses 6.4 2023-08-05 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
616 <li><a href="#h2-NAME">NAME</a></li>
617 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
618 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
620 <li><a href="#h3-USAGE">USAGE</a></li>
623 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
624 <li><a href="#h2-NOTES">NOTES</a></li>
625 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
626 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>