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.15 2010/09/11 22:17:11 tom Exp $
  30 .TH curs_threads 3X ""
  31 .na
  32 .hy 0
  33 .SH NAME
  34 \fBuse_screen\fR,
  35 \fBuse_window\fR \- \fBcurses\fR thread support
  36 .ad
  37 .hy
  38 .SH SYNOPSIS
  39 \fB#include <curses.h>\fR
  40 .sp
  41 \fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR
  42 .br
  43 \fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR
  44 .br
  45 \fBint get_escdelay(void);\fR
  46 .br
  47 \fBint set_escdelay(int size);\fR
  48 .br
  49 \fBint set_tabsize(int size);\fR
  50 .br
  51 \fBint use_screen(SCREEN *scr, NCURSES_WINDOW_CB func, void *data);\fR
  52 .br
  53 \fBint use_window(WINDOW *win, NCURSES_SCREEN_CB func, void *data);\fR
  54 .br
  55 .SH DESCRIPTION
  56 This implementation can be configured to provide rudimentary support
  57 for multi-threaded applications.
  58 This makes a different set of libraries, e.g., \fIlibncursest\fP since
  59 the binary interfaces are different.
  60 .PP
  61 Rather than modify the interfaces to pass a thread specifier to
  62 each function, it adds a few functions which can be used in any
  63 configuration which hide the mutex's needed to prevent concurrent
  64 use of the global variables when configured for threading.
  65 .PP
  66 In addition to forcing access to members of the \fBWINDOW\fP structure
  67 to be via functions (see \fBcurs_opaque\fP(3x)),
  68 it makes functions of the common global variables,
  69 e.g.,
  70 COLORS,
  71 COLOR_PAIRS,
  72 COLS,
  73 ESCDELAY,
  74 LINES,
  75 TABSIZE
  76 curscr,
  77 newscr and
  78 ttytype.
  79 Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
  80 structure.
  81 .PP
  82 Even this is not enough to make a thread-safe application using curses.
  83 A multi-threaded application would be expected to have threads updating
  84 separate windows (within the same device),
  85 or updating on separate screens (on different devices).
  86 Also, a few of the global variables are considered writable by some
  87 applications.
  88 The functions described here address these special situations.
  89 .PP
  90 The ESCDELAY and TABSIZE global variables are modified by some applications.
  91 To modify them in any configuration,
  92 use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
  93 Other global variables are not modifiable.
  94 .PP
  95 The \fBget_escdelay\fP function returns the value for ESCDELAY.
  96 .PP
  97 The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
  98 granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
  99 parameters, and call a user-supplied function,
 100 passing it a \fIdata\fP parameter,
 101 and returning the value from the user-supplied function to the application.
 102 .\" ***************************************************************************
 103 .SS USAGE
 104 All of the ncurses library functions assume that the locale is not
 105 altered during operation.
 106 In addition,
 107 they use data which is maintained within a hierarchy of scopes.
 108 .RS
 109 .TP 3
 110 \-
 111 global data, e.g., used in the low-level terminfo or termcap interfaces.
 112 .TP 3
 113 \-
 114 terminal data, e.g., associated with a call to \fIset_curterm\fP.
 115 The terminal data are initialized when screens are created.
 116 .TP 3
 117 \-
 118 screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP.
 119 .TP 3
 120 \-
 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 .TP 3
 127 \-
 128 reentrant, i.e., it uses only the data passed as parameters.
 129 .RE
 130 .PP
 131 This table lists the scope of data used for each symbol in the
 132 ncurses library when it is configured to support threading:
 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 \fIset_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 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 TRUE or FALSE, 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 .\"#
 604 .\"# The following sets edit modes for GNU EMACS
 605 .\"# Local Variables:
 606 .\"# mode:nroff
 607 .\"# fill-column:79
 608 .\"# End: