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.41 2023/09/16 23:37:03 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-09-16 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-09-16 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> - <EM>curses</EM> 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
73 libraries, 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
77 configuration which hide the mutex's needed to prevent concurrent use
78 of the 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
94 applications. To modify them in any configuration, use the
95 <STRONG>set_escdelay</STRONG> or <STRONG>set_tabsize</STRONG> functions. Other global variables are not
98 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
100 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse granularity
101 mutexes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG> parameters, and call a
102 user-supplied function, passing it a <EM>data</EM> parameter, and returning the
103 value from the user-supplied function to the application.
106 </PRE><H3><a name="h3-USAGE">USAGE</a></H3><PRE>
107 All of the ncurses library functions assume that the locale is not
108 altered during operation. In addition, they use data which is
109 maintained within a hierarchy of scopes.
111 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo or termcap
114 <STRONG>o</STRONG> terminal data, e.g., associated with a call to <STRONG>set_curterm</STRONG>. The
115 terminal data are initialized when screens are created.
117 <STRONG>o</STRONG> screen data, e.g., associated with a call to <STRONG>newterm</STRONG> or <STRONG>initscr</STRONG>.
119 <STRONG>o</STRONG> window data, e.g., associated with a call to <STRONG>newwin</STRONG> or <STRONG>subwin</STRONG>.
120 Windows are associated with screens. Pads are not necessarily
121 associated with a particular screen.
123 Most curses applications operate on one or more windows within a
126 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as parameters.
128 This table lists the scope of data used for each symbol in the ncurses
129 library when it is configured to support threading:
132 -------------------------------------------------------------
134 COLORS screen (readonly)
136 COLOR_PAIRS screen (readonly)
137 COLS screen (readonly)
138 ESCDELAY screen (readonly, see <STRONG>set_escdelay</STRONG>)
139 LINES screen (readonly)
140 PAIR_NUMBER reentrant
143 TABSIZE screen (readonly)
145 acs_map screen (readonly)
146 add_wch window (stdscr)
147 add_wchnstr window (stdscr)
148 add_wchstr window (stdscr)
149 addch window (stdscr)
150 addchnstr window (stdscr)
151 addchstr window (stdscr)
152 addnstr window (stdscr)
153 addnwstr window (stdscr)
154 addstr window (stdscr)
155 addwstr window (stdscr)
156 assume_default_colors screen
157 attr_get window (stdscr)
158 attr_off window (stdscr)
159 attr_on window (stdscr)
160 attr_set window (stdscr)
161 attroff window (stdscr)
162 attron window (stdscr)
163 attrset window (stdscr)
167 bkgdset window (stdscr)
168 bkgrnd window (stdscr)
169 bkgrndset window (stdscr)
170 boolcodes global (readonly)
171 boolfnames global (readonly)
172 boolnames global (readonly)
173 border window (stdscr)
174 border_set window (stdscr)
176 box_set window (stdscr)
177 can_change_color terminal
179 chgat window (stdscr)
180 clear window (stdscr)
183 clrtobot window (stdscr)
184 clrtoeol window (stdscr)
186 color_set window (stdscr)
187 copywin window locks(source, target)
190 curscr screen (readonly)
191 curses_version global (readonly)
192 def_prog_mode terminal
193 def_shell_mode terminal
197 delch window (stdscr)
198 deleteln window (stdscr)
199 delscreen global locks(screenlist, screen)
200 delwin global locks(windowlist)
203 dupwin screen locks(window)
205 echo_wchar window (stdscr)
206 echochar window (stdscr)
208 erase window (stdscr)
209 erasechar window (stdscr)
210 erasewchar window (stdscr)
214 get_wch screen (input-operation)
215 get_wstr screen (input-operation)
222 getch screen (input-operation)
227 getmouse screen (input-operation)
228 getn_wstr screen (input-operation)
229 getnstr screen (input-operation)
232 getstr screen (input-operation)
233 getwin screen (input-operation)
239 hline window (stdscr)
240 hline_set window (stdscr)
244 in_wch window (stdscr)
245 in_wchnstr window (stdscr)
246 in_wchstr window (stdscr)
249 inchnstr window (stdscr)
250 inchstr window (stdscr)
253 initscr global locks(screenlist)
254 innstr window (stdscr)
255 innwstr window (stdscr)
256 ins_nwstr window (stdscr)
257 ins_wch window (stdscr)
258 ins_wstr window (stdscr)
259 insch window (stdscr)
260 insdelln window (stdscr)
261 insertln window (stdscr)
262 insnstr window (stdscr)
263 insstr window (stdscr)
264 instr window (stdscr)
266 inwstr window (stdscr)
273 is_linetouched window
278 is_term_resized terminal
282 key_name global (static data)
284 keyname global (static data)
293 mouse_trafo window (stdscr)
297 mvadd_wch window (stdscr)
298 mvadd_wchnstr window (stdscr)
299 mvadd_wchstr window (stdscr)
300 mvaddch window (stdscr)
301 mvaddchnstr window (stdscr)
302 mvaddchstr window (stdscr)
303 mvaddnstr window (stdscr)
304 mvaddnwstr window (stdscr)
305 mvaddstr window (stdscr)
306 mvaddwstr window (stdscr)
307 mvchgat window (stdscr)
309 mvdelch window (stdscr)
310 mvderwin window (stdscr)
311 mvget_wch screen (input-operation)
312 mvget_wstr screen (input-operation)
313 mvgetch screen (input-operation)
315 mvgetn_wstr screen (input-operation)
316 mvgetnstr screen (input-operation)
317 mvgetstr screen (input-operation)
318 mvhline window (stdscr)
319 mvhline_set window (stdscr)
320 mvin_wch window (stdscr)
321 mvin_wchnstr window (stdscr)
322 mvin_wchstr window (stdscr)
323 mvinch window (stdscr)
324 mvinchnstr window (stdscr)
325 mvinchstr window (stdscr)
326 mvinnstr window (stdscr)
327 mvinnwstr window (stdscr)
328 mvins_nwstr window (stdscr)
329 mvins_wch window (stdscr)
330 mvins_wstr window (stdscr)
331 mvinsch window (stdscr)
332 mvinsnstr window (stdscr)
333 mvinsstr window (stdscr)
334 mvinstr window (stdscr)
335 mvinwstr window (stdscr)
336 mvprintw window (stdscr)
338 mvvline window (stdscr)
339 mvvline_set window (stdscr)
341 mvwadd_wchnstr window
352 mvwget_wch screen (input-operation)
353 mvwget_wstr screen (input-operation)
354 mvwgetch screen (input-operation)
355 mvwgetn_wstr screen (input-operation)
356 mvwgetnstr screen (input-operation)
357 mvwgetstr screen (input-operation)
383 newpad global locks(windowlist)
384 newscr screen (readonly)
385 newterm global locks(screenlist)
386 newwin global locks(windowlist)
396 numcodes global (readonly)
397 numfnames global (readonly)
398 numnames global (readonly)
400 overlay window locks(source, target)
401 overwrite window locks(source, target)
414 reset_prog_mode screen
415 reset_shell_mode screen
417 resize_term screen locks(windowlist)
420 ripoffline global (static data)
433 set_term global locks(screenlist, screen)
435 setscrreg window (stdscr)
449 slk_noutrefresh screen
458 stdscr screen (readonly)
459 strcodes global (readonly)
460 strfnames global (readonly)
461 strnames global (readonly)
476 timeout window (stdscr)
479 tparm global (static data)
481 trace global (static data)
482 ttytype screen (readonly)
485 unget_wch screen (input-operation)
486 ungetch screen (input-operation)
487 ungetmouse screen (input-operation)
489 use_default_colors screen
490 use_env global (static data)
491 use_extended_names global (static data)
492 use_legacy_coding screen
493 use_screen global locks(screenlist, screen)
494 use_window global locks(windowlist, window)
499 vline window (stdscr)
500 vline_set window (stdscr)
534 wcursyncup screen (affects window plus parents)
541 wget_wch screen (input-operation)
542 wget_wstr screen (input-operation)
544 wgetch screen (input-operation)
546 wgetn_wstr screen (input-operation)
547 wgetnstr screen (input-operation)
550 wgetstr screen (input-operation)
577 wresize window locks(windowlist)
584 wsyncdown screen (affects window plus parents)
585 wsyncup screen (affects window plus parents)
588 wunctrl global (static data)
593 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
594 These functions all return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, except as noted.
597 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
598 Both a macro and a function are provided for each name.
601 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
602 These routines are specific to ncurses. They were not supported on
603 Version 7, BSD or System V implementations. It is recommended that any
604 code depending on ncurses extensions be conditioned using
608 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
609 <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>.
613 ncurses 6.4 2023-09-16 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
617 <li><a href="#h2-NAME">NAME</a></li>
618 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
619 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
621 <li><a href="#h3-USAGE">USAGE</a></li>
624 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
625 <li><a href="#h2-NOTES">NOTES</a></li>
626 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
627 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>