man/curs_threads.3x

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