Debian Codegraph @

upstream/debian-unstable/man3/threads.3ncurses

raw
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2021-2024,2025 Thomas E. Dickey *
4 .\" Copyright 2008-2015,2017 Free Software Foundation, Inc. *
5 .\" *
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: *
13 .\" *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
16 .\" *
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. *
24 .\" *
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 *
28 .\" authorization. *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: curs_threads.3x,v 1.59 2025/02/15 19:41:22 tom Exp $
32 .TH threads 3NCURSES 2025-02-15 "ncurses 6.6" "Library calls"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .\}
37 .el \{\
38 .ie t .ds `` ``
39 .el .ds `` ""
40 .ie t .ds '' ''
41 .el .ds '' ""
42 .\}
43 .
44 .de bP
45 .ie n .IP \(bu 4
46 .el .IP \(bu 2
47 ..
48 .SH NAME
49 \fI\%NCURSES_WINDOW_CB\fP,
50 \fI\%NCURSES_SCREEN_CB\fP,
51 \fB\%get_escdelay\fP,
52 \fB\%set_escdelay\fP,
53 \fB\%set_tabsize\fP,
54 \fB\%use_screen\fP,
55 \fB\%use_window\fP \-
56 \fIcurses\fR support for multi-threaded applications
57 .SH SYNOPSIS
58 .nf
59 \fB#include <curses.h>
60 .PP
61 \fI/* data types */
62 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
63 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);
64 .PP
65 \fBint get_escdelay(void);
66 \fBint set_escdelay(int \fIms\fP);
67 \fBint set_tabsize(int \fIcols\fP);
68 .PP
69 \fBint use_screen(SCREEN *\fIscr\fP, NCURSES_SCREEN_CB \fIfunc\fP, void *\fIdata\fP);
70 \fBint use_window(WINDOW *\fIwin\fP, NCURSES_WINDOW_CB \fIfunc\fP, void *\fIdata\fP);
71 .fi
72 .SH DESCRIPTION
73 The \fI\%ncurses\fP library can be configured to support multi-threaded
74 applications in a rudimentary way.
75 Such configuration produces a different set of libraries,
76 named \fIlibncursest\fP,
77 for example,
78 since doing so alters \fI\%ncurses\fP's application binary interface
79 (ABI).
80 .PP
81 Instead of modifying the programming interface (API) to make
82 \fI\%ncurses\fP functions expect an additional argument specifying a
83 thread,
84 the library adds functions,
85 usable in any configuration,
86 that hide the \fImutexes\fP
87 (mutual exclusion locks)
88 needed to prevent concurrent access to variables shared by multiple
89 threads of execution.
90 .PP
91 \fI\%ncurses\fP threading support requires the use of functions to
92 access members of the \fI\%WINDOW\fP structure (see
93 \fBopaque\fP(3NCURSES)).
94 It further makes functions of the common global variables
95 \fB\%COLORS\fP,
96 \fB\%COLOR_PAIRS\fP,
97 \fB\%COLS\fP,
98 \fB\%ESCDELAY\fP,
99 \fB\%LINES\fP,
100 \fB\%TABSIZE\fP,
101 \fB\%curscr\fP,
102 \fB\%newscr\fP,
103 and
104 \fB\%ttytype\fP,
105 maintaining them as read-only values in the \fISCREEN\fP structure.
106 .PP
107 Even this is not enough to make an application using \fIcurses\fP
108 thread-safe.
109 We would expect a multi-threaded application to have threads updating
110 separate windows (on the same device),
111 and separate screens (on different devices).
112 Further,
113 applications expect a few of the global variables to be writable.
114 The functions described here address these special situations.
115 .PP
116 The \fB\%ESCDELAY\fP and \fB\%TABSIZE\fP global variables are modified
117 by some applications.
118 To modify them in any configuration,
119 use the \fB\%set_escdelay\fP or \fB\%set_tabsize\fP functions.
120 Other global variables are not modifiable.
121 \fBget_escdelay\fP retrieves \fB\%ESCDELAY\fP's value.
122 .PP
123 The \fBuse_window\fP and \fBuse_screen\fP functions provide
124 coarse-grained mutexes for their respective \fI\%WINDOW\fP and
125 \fISCREEN\fP parameters;
126 they call a user-supplied function,
127 pass it a \fIdata\fP parameter,
128 and return the value from the user-supplied function to the application.
129 .\" ***************************************************************************
130 .SS Usage
131 All \fI\%ncurses\fP library functions assume that the locale is not
132 altered during operation.
133 In addition,
134 they use data that is maintained within a hierarchy of scopes.
135 .bP
136 global data used in the low-level \fIterminfo\fP or \fItermcap\fP
137 interfaces
138 .bP
139 terminal data associated with a call to \fBset_curterm\fP(3NCURSES)
140 .IP
141 Terminal data are initialized when screens are created.
142 .bP
143 screen data associated with a call to \fBnewterm\fP(3NCURSES) or
144 \fBinitscr\fP(3NCURSES)
145 .bP
146 window data associated with a call to \fBnewwin\fP(3NCURSES) or
147 \fBsubwin\fP(3NCURSES)
148 .IP
149 Windows are associated with screens.
150 Pads are not necessarily associated with any particular screen.
151 .IP
152 Most \fIcurses\fP applications operate on one or more windows within a
153 single screen.
154 .bP
155 reentrant data associated with \*(``pure\*('' functions that alter no
156 shared variables
157 .PP
158 The following table lists the scope of each symbol in the
159 \fI\%ncurses\fP library when configured to support multi-threaded
160 applications.
161 .PP
162 .TS
163 center;
164 Lb2 Lb
165 Lb2 Lx.
166 Symbol Scope
167 _
168 BC global
169 COLORS screen (read-only)
170 COLOR_PAIR reentrant
171 COLOR_PAIRS screen (read-only)
172 COLS screen (read-only)
173 ESCDELAY screen (read-only; see \fBset_escdelay\fP)
174 LINES screen (read-only)
175 PAIR_NUMBER reentrant
176 PC global
177 SP global
178 TABSIZE screen (read-only; see \fBset_tabsize\fP)
179 UP global
180 acs_map screen (read-only)
181 add_wch window (\fBstdscr\fP)
182 add_wchnstr window (\fBstdscr\fP)
183 add_wchstr window (\fBstdscr\fP)
184 addch window (\fBstdscr\fP)
185 addchnstr window (\fBstdscr\fP)
186 addchstr window (\fBstdscr\fP)
187 addnstr window (\fBstdscr\fP)
188 addnwstr window (\fBstdscr\fP)
189 addstr window (\fBstdscr\fP)
190 addwstr window (\fBstdscr\fP)
191 assume_default_colors screen
192 attr_get window (\fBstdscr\fP)
193 attr_off window (\fBstdscr\fP)
194 attr_on window (\fBstdscr\fP)
195 attr_set window (\fBstdscr\fP)
196 attroff window (\fBstdscr\fP)
197 attron window (\fBstdscr\fP)
198 attrset window (\fBstdscr\fP)
199 baudrate screen
200 beep screen
201 bkgd window (\fBstdscr\fP)
202 bkgdset window (\fBstdscr\fP)
203 bkgrnd window (\fBstdscr\fP)
204 bkgrndset window (\fBstdscr\fP)
205 boolcodes global (read-only)
206 boolfnames global (read-only)
207 boolnames global (read-only)
208 border window (\fBstdscr\fP)
209 border_set window (\fBstdscr\fP)
210 box window (\fBstdscr\fP)
211 box_set window (\fBstdscr\fP)
212 can_change_color terminal
213 cbreak screen
214 chgat window (\fBstdscr\fP)
215 clear window (\fBstdscr\fP)
216 clearok window
217 clrtobot window (\fBstdscr\fP)
218 clrtoeol window (\fBstdscr\fP)
219 color_content screen
220 color_set window (\fBstdscr\fP)
221 copywin window (locks source, target)
222 cur_term terminal
223 curs_set screen
224 curscr screen (read-only)
225 curses_version global (read-only)
226 def_prog_mode terminal
227 def_shell_mode terminal
228 define_key screen
229 del_curterm screen
230 delay_output screen
231 delch window (\fBstdscr\fP)
232 deleteln window (\fBstdscr\fP)
233 delscreen global (locks screen list, screen)
234 delwin global (locks window list)
235 derwin screen
236 doupdate screen
237 dupwin screen (locks window)
238 echo screen
239 echo_wchar window (\fBstdscr\fP)
240 echochar window (\fBstdscr\fP)
241 endwin screen
242 erase window (\fBstdscr\fP)
243 erasechar window (\fBstdscr\fP)
244 erasewchar window (\fBstdscr\fP)
245 filter global
246 flash terminal
247 flushinp screen
248 get_wch screen (input operation)
249 get_wstr screen (input operation)
250 getattrs window
251 getbegx window
252 getbegy window
253 getbkgd window
254 getbkgrnd window
255 getcchar reentrant
256 getch screen (input operation)
257 getcurx window
258 getcury window
259 getmaxx window
260 getmaxy window
261 getmouse screen (input operation)
262 getn_wstr screen (input operation)
263 getnstr screen (input operation)
264 getparx window
265 getpary window
266 getstr screen (input operation)
267 getwin screen (input operation)
268 halfdelay screen
269 has_colors terminal
270 has_ic terminal
271 has_il terminal
272 has_key screen
273 hline window (\fBstdscr\fP)
274 hline_set window (\fBstdscr\fP)
275 idcok window
276 idlok window
277 immedok window
278 in_wch window (\fBstdscr\fP)
279 in_wchnstr window (\fBstdscr\fP)
280 in_wchstr window (\fBstdscr\fP)
281 inch window (\fBstdscr\fP)
282 inchnstr window (\fBstdscr\fP)
283 inchstr window (\fBstdscr\fP)
284 init_color screen
285 init_pair screen
286 initscr global (locks screen list)
287 innstr window (\fBstdscr\fP)
288 innwstr window (\fBstdscr\fP)
289 ins_nwstr window (\fBstdscr\fP)
290 ins_wch window (\fBstdscr\fP)
291 ins_wstr window (\fBstdscr\fP)
292 insch window (\fBstdscr\fP)
293 insdelln window (\fBstdscr\fP)
294 insertln window (\fBstdscr\fP)
295 insnstr window (\fBstdscr\fP)
296 insstr window (\fBstdscr\fP)
297 instr window (\fBstdscr\fP)
298 intrflush terminal
299 inwstr window (\fBstdscr\fP)
300 is_cleared window
301 is_idcok window
302 is_idlok window
303 is_immedok window
304 is_keypad window
305 is_leaveok window
306 is_linetouched window
307 is_nodelay window
308 is_notimeout window
309 is_scrollok window
310 is_syncok window
311 is_term_resized terminal
312 is_wintouched window
313 isendwin screen
314 key_defined screen
315 key_name global (static data)
316 keybound screen
317 keyname global (static data)
318 keyok screen
319 keypad window
320 killchar terminal
321 killwchar terminal
322 leaveok window
323 longname screen
324 mcprint terminal
325 meta screen
326 mouse_trafo window (\fBstdscr\fP)
327 mouseinterval screen
328 mousemask screen
329 move window (\fBstdscr\fP)
330 mvadd_wch window (\fBstdscr\fP)
331 mvadd_wchnstr window (\fBstdscr\fP)
332 mvadd_wchstr window (\fBstdscr\fP)
333 mvaddch window (\fBstdscr\fP)
334 mvaddchnstr window (\fBstdscr\fP)
335 mvaddchstr window (\fBstdscr\fP)
336 mvaddnstr window (\fBstdscr\fP)
337 mvaddnwstr window (\fBstdscr\fP)
338 mvaddstr window (\fBstdscr\fP)
339 mvaddwstr window (\fBstdscr\fP)
340 mvchgat window (\fBstdscr\fP)
341 mvcur screen
342 mvdelch window (\fBstdscr\fP)
343 mvderwin window (\fBstdscr\fP)
344 mvget_wch screen (input operation)
345 mvget_wstr screen (input operation)
346 mvgetch screen (input operation)
347 mvgetn_wstr screen (input operation)
348 mvgetnstr screen (input operation)
349 mvgetstr screen (input operation)
350 mvhline window (\fBstdscr\fP)
351 mvhline_set window (\fBstdscr\fP)
352 mvin_wch window (\fBstdscr\fP)
353 mvin_wchnstr window (\fBstdscr\fP)
354 mvin_wchstr window (\fBstdscr\fP)
355 mvinch window (\fBstdscr\fP)
356 mvinchnstr window (\fBstdscr\fP)
357 mvinchstr window (\fBstdscr\fP)
358 mvinnstr window (\fBstdscr\fP)
359 mvinnwstr window (\fBstdscr\fP)
360 mvins_nwstr window (\fBstdscr\fP)
361 mvins_wch window (\fBstdscr\fP)
362 mvins_wstr window (\fBstdscr\fP)
363 mvinsch window (\fBstdscr\fP)
364 mvinsnstr window (\fBstdscr\fP)
365 mvinsstr window (\fBstdscr\fP)
366 mvinstr window (\fBstdscr\fP)
367 mvinwstr window (\fBstdscr\fP)
368 mvprintw window (\fBstdscr\fP)
369 mvscanw screen
370 mvvline window (\fBstdscr\fP)
371 mvvline_set window (\fBstdscr\fP)
372 mvwadd_wch window
373 mvwadd_wchnstr window
374 mvwadd_wchstr window
375 mvwaddch window
376 mvwaddchnstr window
377 mvwaddchstr window
378 mvwaddnstr window
379 mvwaddnwstr window
380 mvwaddstr window
381 mvwaddwstr window
382 mvwchgat window
383 mvwdelch window
384 mvwget_wch screen (input operation)
385 mvwget_wstr screen (input operation)
386 mvwgetch screen (input operation)
387 mvwgetn_wstr screen (input operation)
388 mvwgetnstr screen (input operation)
389 mvwgetstr screen (input operation)
390 mvwhline window
391 mvwhline_set window
392 mvwin window
393 mvwin_wch window
394 mvwin_wchnstr window
395 mvwin_wchstr window
396 mvwinch window
397 mvwinchnstr window
398 mvwinchstr window
399 mvwinnstr window
400 mvwinnwstr window
401 mvwins_nwstr window
402 mvwins_wch window
403 mvwins_wstr window
404 mvwinsch window
405 mvwinsnstr window
406 mvwinsstr window
407 mvwinstr window
408 mvwinwstr window
409 mvwprintw window
410 mvwscanw screen
411 mvwvline window
412 mvwvline_set window
413 napms reentrant
414 newpad global (locks window list)
415 newscr screen (read-only)
416 newterm global (locks screen list)
417 newwin global (locks window list)
418 nl screen
419 nocbreak screen
420 nodelay window
421 noecho screen
422 nofilter global
423 nonl screen
424 noqiflush terminal
425 noraw screen
426 notimeout window
427 numcodes global (read-only)
428 numfnames global (read-only)
429 numnames global (read-only)
430 ospeed global
431 overlay window (locks source, target)
432 overwrite window (locks source, target)
433 pair_content screen
434 pecho_wchar screen
435 pechochar screen
436 pnoutrefresh screen
437 prefresh screen
438 printw window
439 putp global
440 putwin window
441 qiflush terminal
442 raw screen
443 redrawwin window
444 refresh screen
445 reset_prog_mode screen
446 reset_shell_mode screen
447 resetty terminal
448 resize_term screen (locks window list)
449 resizeterm screen
450 restartterm screen
451 ripoffline global (static data)
452 savetty terminal
453 scanw screen
454 scr_dump screen
455 scr_init screen
456 scr_restore screen
457 scr_set screen
458 scrl window (\fBstdscr\fP)
459 scroll window
460 scrollok window
461 set_curterm screen
462 set_escdelay screen
463 set_tabsize screen
464 set_term global (locks screen list, screen)
465 setcchar reentrant
466 setscrreg window (\fBstdscr\fP)
467 setupterm global
468 slk_attr screen
469 slk_attr_off screen
470 slk_attr_on screen
471 slk_attr_set screen
472 slk_attroff screen
473 slk_attron screen
474 slk_attrset screen
475 slk_clear screen
476 slk_color screen
477 slk_init screen
478 slk_label screen
479 slk_noutrefresh screen
480 slk_refresh screen
481 slk_restore screen
482 slk_set screen
483 slk_touch screen
484 slk_wset screen
485 standend window
486 standout window
487 start_color screen
488 \fBstdscr\fP screen (read-only)
489 strcodes global (read-only)
490 strfnames global (read-only)
491 strnames global (read-only)
492 subpad window
493 subwin window
494 syncok window
495 term_attrs screen
496 termattrs screen
497 termname terminal
498 tgetent global
499 tgetflag global
500 tgetnum global
501 tgetstr global
502 tgoto global
503 tigetflag terminal
504 tigetnum terminal
505 tigetstr terminal
506 timeout window (\fBstdscr\fP)
507 touchline window
508 touchwin window
509 tparm global (static data)
510 tputs screen
511 trace global (static data)
512 ttytype screen (read-only)
513 typeahead screen
514 unctrl screen
515 unget_wch screen (input operation)
516 ungetch screen (input operation)
517 ungetmouse screen (input operation)
518 untouchwin window
519 use_default_colors screen
520 use_env global (static data)
521 use_extended_names global (static data)
522 use_legacy_coding screen
523 use_screen global (locks screen list, screen)
524 use_window global (locks window list, window)
525 vid_attr screen
526 vid_puts screen
527 vidattr screen
528 vidputs screen
529 vline window (\fBstdscr\fP)
530 vline_set window (\fBstdscr\fP)
531 vw_printw window
532 vw_scanw screen
533 vwprintw window
534 vwscanw screen
535 wadd_wch window
536 wadd_wchnstr window
537 wadd_wchstr window
538 waddch window
539 waddchnstr window
540 waddchstr window
541 waddnstr window
542 waddnwstr window
543 waddstr window
544 waddwstr window
545 wattr_get window
546 wattr_off window
547 wattr_on window
548 wattr_set window
549 wattroff window
550 wattron window
551 wattrset window
552 wbkgd window
553 wbkgdset window
554 wbkgrnd window
555 wbkgrndset window
556 wborder window
557 wborder_set window
558 wchgat window
559 wclear window
560 wclrtobot window
561 wclrtoeol window
562 wcolor_set window
563 wcursyncup screen (affects window plus parents)
564 wdelch window
565 wdeleteln window
566 wecho_wchar window
567 wechochar window
568 wenclose window
569 werase window
570 wget_wch screen (input operation)
571 wget_wstr screen (input operation)
572 wgetbkgrnd window
573 wgetch screen (input operation)
574 wgetdelay window
575 wgetn_wstr screen (input operation)
576 wgetnstr screen (input operation)
577 wgetparent window
578 wgetscrreg window
579 wgetstr screen (input operation)
580 whline window
581 whline_set window
582 win_wch window
583 win_wchnstr window
584 win_wchstr window
585 winch window
586 winchnstr window
587 winchstr window
588 winnstr window
589 winnwstr window
590 wins_nwstr window
591 wins_wch window
592 wins_wstr window
593 winsch window
594 winsdelln window
595 winsertln window
596 winsnstr window
597 winsstr window
598 winstr window
599 winwstr window
600 wmouse_trafo window
601 wmove window
602 wnoutrefresh screen
603 wprintw window
604 wredrawln window
605 wrefresh screen
606 wresize window (locks window list)
607 wscanw screen
608 wscrl window
609 wsetscrreg window
610 wstandend window
611 wstandout window
612 wsyncdown screen (affects window plus parents)
613 wsyncup screen (affects window plus parents)
614 wtimeout window
615 wtouchln window
616 wunctrl global (static data)
617 wvline window
618 wvline_set window
619 .TE
620 .\" ***************************************************************************
621 .SH RETURN VALUE
622 \fB\%get_escdelay\fP returns the value of \fB\%ESCDELAY\fP.
623 \fB\%set_escdelay\fP and \fB\%set_tabsize\fP return \fBERR\fP upon
624 failure and \fBOK\fP upon successful completion.
625 \fB\%use_screen\fP and \fB\%use_window\fP return the \fIint\fP returned
626 by the user-supplied function they are called with.
627 .SH NOTES
628 \fI\%ncurses\fP provides both a C function and a preprocessor macro for
629 each function documented in this page.
630 .SH PORTABILITY
631 These routines are specific to \fI\%ncurses\fP.
632 They were not supported on Version 7, BSD or System V implementations.
633 It is recommended that any code depending on \fI\%ncurses\fP extensions
634 be conditioned using \fB\%NCURSES_VERSION\fP.
635 .SH SEE ALSO
636 \fB\%ncurses\fP(3NCURSES),
637 \fB\%opaque\fP(3NCURSES),
638 \fB\%curses_variables\fP(3NCURSES)