man/curs_threads.3x

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