2 ****************************************************************************
3 * Copyright (c) 2008-2014,2015 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.23 2015/12/05 18:47:04 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 http://invisible-island.net/scripts/readme.html#others_scripts">
38 <TITLE>curs_threads 3x</TITLE>
39 <link rev=made 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>
63 <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>
65 <STRONG>*data);</STRONG>
68 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
69 This implementation can be configured to provide rudimen-
70 tary support for multi-threaded applications. This makes
71 a different set of libraries, e.g., <EM>libncursest</EM> since the
72 binary interfaces are different.
74 Rather than modify the interfaces to pass a thread speci-
75 fier to each function, it adds a few functions which can
76 be used in any configuration which hide the mutex's needed
77 to prevent concurrent use of the global variables when
78 configured for threading.
80 In addition to forcing access to members of the <STRONG>WINDOW</STRONG>
81 structure to be via functions (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>), it
82 makes functions of the common global variables, e.g., COL-
83 ORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE curscr,
84 newscr and ttytype. Those variables are maintained as
85 read-only values, stored in the <STRONG>SCREEN</STRONG> structure.
87 Even this is not enough to make a thread-safe application
88 using curses. A multi-threaded application would be ex-
89 pected to have threads updating separate windows (within
90 the same device), or updating on separate screens (on dif-
91 ferent devices). Also, a few of the global variables are
92 considered writable by some applications. The functions
93 described here address these special situations.
95 The ESCDELAY and TABSIZE global variables are modified by
96 some applications. To modify them in any configuration,
97 use the <STRONG>set_escdelay</STRONG> or <STRONG>set_tabsize</STRONG> functions. Other
98 global variables are not modifiable.
100 The <STRONG>get_escdelay</STRONG> function returns the value for ESCDELAY.
102 The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse
103 granularity mutexes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG>
104 parameters, and call a user-supplied function, passing it
105 a <EM>data</EM> parameter, and returning the value from the user-
106 supplied function to the application.
109 </PRE><H3><a name="h3-USAGE">USAGE</a></H3><PRE>
110 All of the ncurses library functions assume that the lo-
111 cale is not altered during operation. In addition, they
112 use data which is maintained within a hierarchy of scopes.
114 <STRONG>o</STRONG> global data, e.g., used in the low-level terminfo
115 or termcap interfaces.
117 <STRONG>o</STRONG> terminal data, e.g., associated with a call to
118 <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. The terminal data are initialized
119 when screens are created.
121 <STRONG>o</STRONG> screen data, e.g., associated with a call to
122 <EM>newterm</EM> or <EM>initscr</EM>.
124 <STRONG>o</STRONG> window data, e.g., associated with a call to <EM>newwin</EM>
125 or <EM>subwin</EM>. Windows are associated with screens.
126 Pads are not necessarily associated with a particu-
129 Most curses applications operate on one or more
130 windows within a single screen.
132 <STRONG>o</STRONG> reentrant, i.e., it uses only the data passed as
135 This table lists the scope of data used for each symbol in
136 the ncurses library when it is configured to support
140 -------------------------------------------------------------
142 COLORS screen (readonly)
144 COLOR_PAIRS screen (readonly)
145 COLS screen (readonly)
146 ESCDELAY screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
147 LINES screen (readonly)
148 PAIR_NUMBER reentrant
151 TABSIZE screen (readonly)
153 acs_map screen (readonly)
154 add_wch window (stdscr)
155 add_wchnstr window (stdscr)
156 add_wchstr window (stdscr)
157 addch window (stdscr)
158 addchnstr window (stdscr)
159 addchstr window (stdscr)
160 addnstr window (stdscr)
161 addnwstr window (stdscr)
162 addstr window (stdscr)
163 addwstr window (stdscr)
164 assume_default_colors screen
165 attr_get window (stdscr)
166 attr_off window (stdscr)
167 attr_on window (stdscr)
168 attr_set window (stdscr)
169 attroff window (stdscr)
170 attron window (stdscr)
171 attrset window (stdscr)
175 bkgdset window (stdscr)
176 bkgrnd window (stdscr)
177 bkgrndset window (stdscr)
178 boolcodes global (readonly)
179 boolfnames global (readonly)
180 boolnames global (readonly)
181 border window (stdscr)
183 border_set window (stdscr)
185 box_set window (stdscr)
186 can_change_color terminal
188 chgat window (stdscr)
189 clear window (stdscr)
191 clrtobot window (stdscr)
192 clrtoeol window (stdscr)
194 color_set window (stdscr)
195 copywin window locks(source, target)
198 curscr screen (readonly)
199 curses_version global (readonly)
200 def_prog_mode terminal
201 def_shell_mode terminal
205 delch window (stdscr)
206 deleteln window (stdscr)
207 delscreen global locks(screenlist, screen)
208 delwin global locks(windowlist)
211 dupwin screen locks(window)
213 echo_wchar window (stdscr)
214 echochar window (stdscr)
216 erase window (stdscr)
217 erasechar window (stdscr)
218 erasewchar window (stdscr)
222 get_wch screen (input-operation)
223 get_wstr screen (input-operation)
230 getch screen (input-operation)
235 getmouse screen (input-operation)
236 getn_wstr screen (input-operation)
237 getnstr screen (input-operation)
240 getstr screen (input-operation)
241 getwin screen (input-operation)
247 hline window (stdscr)
248 hline_set window (stdscr)
253 in_wch window (stdscr)
254 in_wchnstr window (stdscr)
255 in_wchstr window (stdscr)
257 inchnstr window (stdscr)
258 inchstr window (stdscr)
261 initscr global locks(screenlist)
262 innstr window (stdscr)
263 innwstr window (stdscr)
264 ins_nwstr window (stdscr)
265 ins_wch window (stdscr)
266 ins_wstr window (stdscr)
267 insch window (stdscr)
268 insdelln window (stdscr)
269 insertln window (stdscr)
270 insnstr window (stdscr)
271 insstr window (stdscr)
272 instr window (stdscr)
274 inwstr window (stdscr)
281 is_linetouched window
286 is_term_resized terminal
290 key_name global (static data)
292 keyname global (static data)
301 mouse_trafo window (stdscr)
305 mvadd_wch window (stdscr)
306 mvadd_wchnstr window (stdscr)
307 mvadd_wchstr window (stdscr)
308 mvaddch window (stdscr)
309 mvaddchnstr window (stdscr)
310 mvaddchstr window (stdscr)
311 mvaddnstr window (stdscr)
312 mvaddnwstr window (stdscr)
313 mvaddstr window (stdscr)
314 mvaddwstr window (stdscr)
315 mvchgat window (stdscr)
318 mvdelch window (stdscr)
319 mvderwin window (stdscr)
320 mvget_wch screen (input-operation)
321 mvget_wstr screen (input-operation)
322 mvgetch screen (input-operation)
323 mvgetn_wstr screen (input-operation)
324 mvgetnstr screen (input-operation)
325 mvgetstr screen (input-operation)
326 mvhline window (stdscr)
327 mvhline_set window (stdscr)
328 mvin_wch window (stdscr)
329 mvin_wchnstr window (stdscr)
330 mvin_wchstr window (stdscr)
331 mvinch window (stdscr)
332 mvinchnstr window (stdscr)
333 mvinchstr window (stdscr)
334 mvinnstr window (stdscr)
335 mvinnwstr window (stdscr)
336 mvins_nwstr window (stdscr)
337 mvins_wch window (stdscr)
338 mvins_wstr window (stdscr)
339 mvinsch window (stdscr)
340 mvinsnstr window (stdscr)
341 mvinsstr window (stdscr)
342 mvinstr window (stdscr)
343 mvinwstr window (stdscr)
344 mvprintw window (stdscr)
346 mvvline window (stdscr)
347 mvvline_set window (stdscr)
349 mvwadd_wchnstr window
360 mvwget_wch screen (input-operation)
361 mvwget_wstr screen (input-operation)
362 mvwgetch screen (input-operation)
363 mvwgetn_wstr screen (input-operation)
364 mvwgetnstr screen (input-operation)
365 mvwgetstr screen (input-operation)
391 newpad global locks(windowlist)
392 newscr screen (readonly)
393 newterm global locks(screenlist)
394 newwin global locks(windowlist)
404 numcodes global (readonly)
405 numfnames global (readonly)
406 numnames global (readonly)
408 overlay window locks(source, target)
409 overwrite window locks(source, target)
422 reset_prog_mode screen
423 reset_shell_mode screen
425 resize_term screen locks(windowlist)
428 ripoffline global (static data)
441 set_term global locks(screenlist, screen)
443 setscrreg window (stdscr)
457 slk_noutrefresh screen
466 stdscr screen (readonly)
467 strcodes global (readonly)
468 strfnames global (readonly)
469 strnames global (readonly)
484 timeout window (stdscr)
487 tparm global (static data)
489 trace global (static data)
490 ttytype screen (readonly)
493 unget_wch screen (input-operation)
494 ungetch screen (input-operation)
495 ungetmouse screen (input-operation)
497 use_default_colors screen
498 use_env global (static data)
499 use_extended_names global (static data)
500 use_legacy_coding screen
501 use_screen global locks(screenlist, screen)
502 use_window global locks(windowlist, window)
507 vline window (stdscr)
508 vline_set window (stdscr)
542 wcursyncup screen (affects window plus parents)
549 wget_wch screen (input-operation)
550 wget_wstr screen (input-operation)
552 wgetch screen (input-operation)
554 wgetn_wstr screen (input-operation)
555 wgetnstr screen (input-operation)
558 wgetstr screen (input-operation)
586 wresize window locks(windowlist)
592 wsyncdown screen (affects window plus parents)
593 wsyncup screen (affects window plus parents)
596 wunctrl global (static data)
601 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
602 These functions all return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, except as noted.
605 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
606 Both a macro and a function are provided for each name.
609 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
610 These routines are specific to ncurses. They were not
611 supported on Version 7, BSD or System V implementations.
612 It is recommended that any code depending on ncurses ex-
613 tensions be conditioned using NCURSES_VERSION.
616 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
617 <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>.
621 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
625 <li><a href="#h2-NAME">NAME</a></li>
626 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
627 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
629 <li><a href="#h3-USAGE">USAGE</a></li>
632 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
633 <li><a href="#h2-NOTES">NOTES</a></li>
634 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
635 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>