man/curs_threads.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2020 Thomas E. Dickey                                          *
   3 .\" Copyright 2008-2015,2017 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   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:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  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.                               *
  23 .\"                                                                          *
  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       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: curs_threads.3x,v 1.25 2020/02/02 23:34:34 tom Exp $
  31 .TH curs_threads 3X ""
  32 .de bP
  33 .ie n  .IP \(bu 4
  34 .el    .IP \(bu 2
  35 ..
  36 .na
  37 .hy 0
  38 .SH NAME
  39 \fBcurs_threads\fR \- \fBcurses\fR thread support
  40 .ad
  41 .hy
  42 .SH SYNOPSIS
  43 \fB#include <curses.h>\fR
  44 .sp
  45 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR
  46 .br
  47 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR
  48 .br
  49 \fBint get_escdelay(void);\fR
  50 .br
  51 \fBint set_escdelay(int size);\fR
  52 .br
  53 \fBint set_tabsize(int size);\fR
  54 .br
  55 \fBint use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);\fR
  56 .br
  57 \fBint use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);\fR
  58 .br
  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., \fIlibncursest\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 \fIset_curterm\fP.
 117 The terminal data are initialized when screens are created.
 118 .bP
 119 screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP.
 120 .bP
 121 window data, e.g., associated with a call to \fInewwin\fP or \fIsubwin\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 .TS
 133 center tab(/);
 134 l l
 135 l l .
 136 Symbol/Scope
 137 =
 138 BC/global
 139 COLORS/screen (readonly)
 140 COLOR_PAIR/reentrant
 141 COLOR_PAIRS/screen (readonly)
 142 COLS/screen (readonly)
 143 ESCDELAY/screen (readonly, see \fIset_escdelay\fP)
 144 LINES/screen (readonly)
 145 PAIR_NUMBER/reentrant
 146 PC/global
 147 SP/global
 148 TABSIZE/screen (readonly)
 149 UP/global
 150 acs_map/screen (readonly)
 151 add_wch/window (stdscr)
 152 add_wchnstr/window (stdscr)
 153 add_wchstr/window (stdscr)
 154 addch/window (stdscr)
 155 addchnstr/window (stdscr)
 156 addchstr/window (stdscr)
 157 addnstr/window (stdscr)
 158 addnwstr/window (stdscr)
 159 addstr/window (stdscr)
 160 addwstr/window (stdscr)
 161 assume_default_colors/screen
 162 attr_get/window (stdscr)
 163 attr_off/window (stdscr)
 164 attr_on/window (stdscr)
 165 attr_set/window (stdscr)
 166 attroff/window (stdscr)
 167 attron/window (stdscr)
 168 attrset/window (stdscr)
 169 baudrate/screen
 170 beep/screen
 171 bkgd/window (stdscr)
 172 bkgdset/window (stdscr)
 173 bkgrnd/window (stdscr)
 174 bkgrndset/window (stdscr)
 175 boolcodes/global (readonly)
 176 boolfnames/global (readonly)
 177 boolnames/global (readonly)
 178 border/window (stdscr)
 179 border_set/window (stdscr)
 180 box/window (stdscr)
 181 box_set/window (stdscr)
 182 can_change_color/terminal
 183 cbreak/screen
 184 chgat/window (stdscr)
 185 clear/window (stdscr)
 186 clearok/window
 187 clrtobot/window (stdscr)
 188 clrtoeol/window (stdscr)
 189 color_content/screen
 190 color_set/window (stdscr)
 191 copywin/window locks(source, target)
 192 cur_term/terminal
 193 curs_set/screen
 194 curscr/screen (readonly)
 195 curses_version/global (readonly)
 196 def_prog_mode/terminal
 197 def_shell_mode/terminal
 198 define_key/screen
 199 del_curterm/screen
 200 delay_output/screen
 201 delch/window (stdscr)
 202 deleteln/window (stdscr)
 203 delscreen/global locks(screenlist, screen)
 204 delwin/global locks(windowlist)
 205 derwin/screen
 206 doupdate/screen
 207 dupwin/screen locks(window)
 208 echo/screen
 209 echo_wchar/window (stdscr)
 210 echochar/window (stdscr)
 211 endwin/screen
 212 erase/window (stdscr)
 213 erasechar/window (stdscr)
 214 erasewchar/window (stdscr)
 215 filter/global
 216 flash/terminal
 217 flushinp/screen
 218 get_wch/screen (input-operation)
 219 get_wstr/screen (input-operation)
 220 getattrs/window
 221 getbegx/window
 222 getbegy/window
 223 getbkgd/window
 224 getbkgrnd/window
 225 getcchar/reentrant
 226 getch/screen (input-operation)
 227 getcurx/window
 228 getcury/window
 229 getmaxx/window
 230 getmaxy/window
 231 getmouse/screen (input-operation)
 232 getn_wstr/screen (input-operation)
 233 getnstr/screen (input-operation)
 234 getparx/window
 235 getpary/window
 236 getstr/screen (input-operation)
 237 getwin/screen (input-operation)
 238 halfdelay/screen
 239 has_colors/terminal
 240 has_ic/terminal
 241 has_il/terminal
 242 has_key/screen
 243 hline/window (stdscr)
 244 hline_set/window (stdscr)
 245 idcok/window
 246 idlok/window
 247 immedok/window
 248 in_wch/window (stdscr)
 249 in_wchnstr/window (stdscr)
 250 in_wchstr/window (stdscr)
 251 inch/window (stdscr)
 252 inchnstr/window (stdscr)
 253 inchstr/window (stdscr)
 254 init_color/screen
 255 init_pair/screen
 256 initscr/global locks(screenlist)
 257 innstr/window (stdscr)
 258 innwstr/window (stdscr)
 259 ins_nwstr/window (stdscr)
 260 ins_wch/window (stdscr)
 261 ins_wstr/window (stdscr)
 262 insch/window (stdscr)
 263 insdelln/window (stdscr)
 264 insertln/window (stdscr)
 265 insnstr/window (stdscr)
 266 insstr/window (stdscr)
 267 instr/window (stdscr)
 268 intrflush/terminal
 269 inwstr/window (stdscr)
 270 is_cleared/window
 271 is_idcok/window
 272 is_idlok/window
 273 is_immedok/window
 274 is_keypad/window
 275 is_leaveok/window
 276 is_linetouched/window
 277 is_nodelay/window
 278 is_notimeout/window
 279 is_scrollok/window
 280 is_syncok/window
 281 is_term_resized/terminal
 282 is_wintouched/window
 283 isendwin/screen
 284 key_defined/screen
 285 key_name/global (static data)
 286 keybound/screen
 287 keyname/global (static data)
 288 keyok/screen
 289 keypad/window
 290 killchar/terminal
 291 killwchar/terminal
 292 leaveok/window
 293 longname/screen
 294 mcprint/terminal
 295 meta/screen
 296 mouse_trafo/window (stdscr)
 297 mouseinterval/screen
 298 mousemask/screen
 299 move/window (stdscr)
 300 mvadd_wch/window (stdscr)
 301 mvadd_wchnstr/window (stdscr)
 302 mvadd_wchstr/window (stdscr)
 303 mvaddch/window (stdscr)
 304 mvaddchnstr/window (stdscr)
 305 mvaddchstr/window (stdscr)
 306 mvaddnstr/window (stdscr)
 307 mvaddnwstr/window (stdscr)
 308 mvaddstr/window (stdscr)
 309 mvaddwstr/window (stdscr)
 310 mvchgat/window (stdscr)
 311 mvcur/screen
 312 mvdelch/window (stdscr)
 313 mvderwin/window (stdscr)
 314 mvget_wch/screen (input-operation)
 315 mvget_wstr/screen (input-operation)
 316 mvgetch/screen (input-operation)
 317 mvgetn_wstr/screen (input-operation)
 318 mvgetnstr/screen (input-operation)
 319 mvgetstr/screen (input-operation)
 320 mvhline/window (stdscr)
 321 mvhline_set/window (stdscr)
 322 mvin_wch/window (stdscr)
 323 mvin_wchnstr/window (stdscr)
 324 mvin_wchstr/window (stdscr)
 325 mvinch/window (stdscr)
 326 mvinchnstr/window (stdscr)
 327 mvinchstr/window (stdscr)
 328 mvinnstr/window (stdscr)
 329 mvinnwstr/window (stdscr)
 330 mvins_nwstr/window (stdscr)
 331 mvins_wch/window (stdscr)
 332 mvins_wstr/window (stdscr)
 333 mvinsch/window (stdscr)
 334 mvinsnstr/window (stdscr)
 335 mvinsstr/window (stdscr)
 336 mvinstr/window (stdscr)
 337 mvinwstr/window (stdscr)
 338 mvprintw/window (stdscr)
 339 mvscanw/screen
 340 mvvline/window (stdscr)
 341 mvvline_set/window (stdscr)
 342 mvwadd_wch/window
 343 mvwadd_wchnstr/window
 344 mvwadd_wchstr/window
 345 mvwaddch/window
 346 mvwaddchnstr/window
 347 mvwaddchstr/window
 348 mvwaddnstr/window
 349 mvwaddnwstr/window
 350 mvwaddstr/window
 351 mvwaddwstr/window
 352 mvwchgat/window
 353 mvwdelch/window
 354 mvwget_wch/screen (input-operation)
 355 mvwget_wstr/screen (input-operation)
 356 mvwgetch/screen (input-operation)
 357 mvwgetn_wstr/screen (input-operation)
 358 mvwgetnstr/screen (input-operation)
 359 mvwgetstr/screen (input-operation)
 360 mvwhline/window
 361 mvwhline_set/window
 362 mvwin/window
 363 mvwin_wch/window
 364 mvwin_wchnstr/window
 365 mvwin_wchstr/window
 366 mvwinch/window
 367 mvwinchnstr/window
 368 mvwinchstr/window
 369 mvwinnstr/window
 370 mvwinnwstr/window
 371 mvwins_nwstr/window
 372 mvwins_wch/window
 373 mvwins_wstr/window
 374 mvwinsch/window
 375 mvwinsnstr/window
 376 mvwinsstr/window
 377 mvwinstr/window
 378 mvwinwstr/window
 379 mvwprintw/window
 380 mvwscanw/screen
 381 mvwvline/window
 382 mvwvline_set/window
 383 napms/reentrant
 384 newpad/global locks(windowlist)
 385 newscr/screen (readonly)
 386 newterm/global locks(screenlist)
 387 newwin/global locks(windowlist)
 388 nl/screen
 389 nocbreak/screen
 390 nodelay/window
 391 noecho/screen
 392 nofilter/global
 393 nonl/screen
 394 noqiflush/terminal
 395 noraw/screen
 396 notimeout/window
 397 numcodes/global (readonly)
 398 numfnames/global (readonly)
 399 numnames/global (readonly)
 400 ospeed/global
 401 overlay/window locks(source, target)
 402 overwrite/window locks(source, target)
 403 pair_content/screen
 404 pecho_wchar/screen
 405 pechochar/screen
 406 pnoutrefresh/screen
 407 prefresh/screen
 408 printw/window
 409 putp/global
 410 putwin/window
 411 qiflush/terminal
 412 raw/screen
 413 redrawwin/window
 414 refresh/screen
 415 reset_prog_mode/screen
 416 reset_shell_mode/screen
 417 resetty/terminal
 418 resize_term/screen locks(windowlist)
 419 resizeterm/screen
 420 restartterm/screen
 421 ripoffline/global (static data)
 422 savetty/terminal
 423 scanw/screen
 424 scr_dump/screen
 425 scr_init/screen
 426 scr_restore/screen
 427 scr_set/screen
 428 scrl/window (stdscr)
 429 scroll/window
 430 scrollok/window
 431 set_curterm/screen
 432 set_escdelay/screen
 433 set_tabsize/screen
 434 set_term/global locks(screenlist, screen)
 435 setcchar/reentrant
 436 setscrreg/window (stdscr)
 437 setupterm/global
 438 slk_attr/screen
 439 slk_attr_off/screen
 440 slk_attr_on/screen
 441 slk_attr_set/screen
 442 slk_attroff/screen
 443 slk_attron/screen
 444 slk_attrset/screen
 445 slk_clear/screen
 446 slk_color/screen
 447 slk_init/screen
 448 slk_label/screen
 449 slk_noutrefresh/screen
 450 slk_refresh/screen
 451 slk_restore/screen
 452 slk_set/screen
 453 slk_touch/screen
 454 slk_wset/screen
 455 standend/window
 456 standout/window
 457 start_color/screen
 458 stdscr/screen (readonly)
 459 strcodes/global (readonly)
 460 strfnames/global (readonly)
 461 strnames/global (readonly)
 462 subpad/window
 463 subwin/window
 464 syncok/window
 465 term_attrs/screen
 466 termattrs/screen
 467 termname/terminal
 468 tgetent/global
 469 tgetflag/global
 470 tgetnum/global
 471 tgetstr/global
 472 tgoto/global
 473 tigetflag/terminal
 474 tigetnum/terminal
 475 tigetstr/terminal
 476 timeout/window (stdscr)
 477 touchline/window
 478 touchwin/window
 479 tparm/global (static data)
 480 tputs/screen
 481 trace/global (static data)
 482 ttytype/screen (readonly)
 483 typeahead/screen
 484 unctrl/screen
 485 unget_wch/screen (input-operation)
 486 ungetch/screen (input-operation)
 487 ungetmouse/screen (input-operation)
 488 untouchwin/window
 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)
 495 vid_attr/screen
 496 vid_puts/screen
 497 vidattr/screen
 498 vidputs/screen
 499 vline/window (stdscr)
 500 vline_set/window (stdscr)
 501 vw_printw/window
 502 vw_scanw/screen
 503 vwprintw/window
 504 vwscanw/screen
 505 wadd_wch/window
 506 wadd_wchnstr/window
 507 wadd_wchstr/window
 508 waddch/window
 509 waddchnstr/window
 510 waddchstr/window
 511 waddnstr/window
 512 waddnwstr/window
 513 waddstr/window
 514 waddwstr/window
 515 wattr_get/window
 516 wattr_off/window
 517 wattr_on/window
 518 wattr_set/window
 519 wattroff/window
 520 wattron/window
 521 wattrset/window
 522 wbkgd/window
 523 wbkgdset/window
 524 wbkgrnd/window
 525 wbkgrndset/window
 526 wborder/window
 527 wborder_set/window
 528 wchgat/window
 529 wclear/window
 530 wclrtobot/window
 531 wclrtoeol/window
 532 wcolor_set/window
 533 wcursyncup/screen (affects window plus parents)
 534 wdelch/window
 535 wdeleteln/window
 536 wecho_wchar/window
 537 wechochar/window
 538 wenclose/window
 539 werase/window
 540 wget_wch/screen (input-operation)
 541 wget_wstr/screen (input-operation)
 542 wgetbkgrnd/window
 543 wgetch/screen (input-operation)
 544 wgetdelay/window
 545 wgetn_wstr/screen (input-operation)
 546 wgetnstr/screen (input-operation)
 547 wgetparent/window
 548 wgetscrreg/window
 549 wgetstr/screen (input-operation)
 550 whline/window
 551 whline_set/window
 552 win_wch/window
 553 win_wchnstr/window
 554 win_wchstr/window
 555 winch/window
 556 winchnstr/window
 557 winchstr/window
 558 winnstr/window
 559 winnwstr/window
 560 wins_nwstr/window
 561 wins_wch/window
 562 wins_wstr/window
 563 winsch/window
 564 winsdelln/window
 565 winsertln/window
 566 winsnstr/window
 567 winsstr/window
 568 winstr/window
 569 winwstr/window
 570 wmouse_trafo/window
 571 wmove/window
 572 wnoutrefresh/screen
 573 wprintw/window
 574 wredrawln/window
 575 wrefresh/screen
 576 wresize/window locks(windowlist)
 577 wscanw/screen
 578 wscrl/window
 579 wsetscrreg/window
 580 wstandend/window
 581 wstandout/window
 582 wsyncdown/screen (affects window plus parents)
 583 wsyncup/screen (affects window plus parents)
 584 wtimeout/window
 585 wtouchln/window
 586 wunctrl/global (static data)
 587 wvline/window
 588 wvline_set/window
 589 .TE
 590 .\" ***************************************************************************
 591 .SH RETURN VALUE
 592 These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
 593 .SH NOTES
 594 Both a macro and a function are provided for each name.
 595 .SH PORTABILITY
 596 These routines are specific to ncurses.
 597 They were not supported on Version 7, BSD or System V implementations.
 598 It is recommended that any code depending on ncurses extensions
 599 be conditioned using NCURSES_VERSION.
 600 .SH SEE ALSO
 601 \fBcurses\fR(3X),
 602 \fBcurs_opaque\fR(3X),
 603 \fBcurs_variables\fR(3X).