doc/html/man/curs_threads.3x.html

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