man/curs_threads.3x

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