<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<!-- 
  ****************************************************************************
  * Copyright (c) 2008 Free Software Foundation, Inc.                        *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_threads.3x,v 1.12 2008/04/12 18:22:51 tom Exp @
  * ***************************************************************************
  * ***************************************************************************
-->
<HTML>
<HEAD>
<TITLE>curs_threads 3x</TITLE>
<link rev=made href="mailto:bug-ncurses@gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY>
<H1>curs_threads 3x</H1>
<HR>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
<STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>                                       <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>


</PRE>
<H2>NAME</H2><PRE>
       <STRONG>use_screen</STRONG>, <STRONG>use_window</STRONG> - <STRONG>curses</STRONG> thread support


</PRE>
<H2>SYNOPSIS</H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>

       <STRONG>typedef</STRONG>  <STRONG>int</STRONG> <STRONG>(*NCURSES_WINDOW_CB)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG> <STRONG>type-</STRONG>
       <STRONG>def</STRONG> <STRONG>int</STRONG> <STRONG>(*NCURSES_SCREEN_CB)(SCREEN</STRONG> <STRONG>*,</STRONG> <STRONG>void</STRONG> <STRONG>*);</STRONG>
       <STRONG>int</STRONG> <STRONG>set_escdelay(int</STRONG> <STRONG>size);</STRONG>
       <STRONG>int</STRONG> <STRONG>set_tabsize(int</STRONG> <STRONG>size);</STRONG>
       <STRONG>int</STRONG> <STRONG>use_screen(SCREEN</STRONG> <STRONG>*scr,</STRONG> <STRONG>NCURSES_WINDOW_CB</STRONG>  <STRONG>func,</STRONG>  <STRONG>void</STRONG>
       <STRONG>*data);</STRONG>
       <STRONG>int</STRONG>  <STRONG>use_window(WINDOW</STRONG>  <STRONG>*win,</STRONG> <STRONG>NCURSES_SCREEN_CB</STRONG> <STRONG>func,</STRONG> <STRONG>void</STRONG>
       <STRONG>*data);</STRONG>


</PRE>
<H2>DESCRIPTION</H2><PRE>
       This implementation can be configured to provide  rudimen-
       tary  support for multi-threaded applications.  This makes
       a different set of libraries, e.g., <EM>libncursest</EM> since  the
       binary interfaces are different.

       Rather  than modify the interfaces to pass a thread speci-
       fier to each function, it adds a few functions  which  can
       be used in any configuration which hide the mutex's needed
       to prevent concurrent use of  the  global  variables  when
       configured for threading.

       In  addition  to  forcing  access to members of the <STRONG>WINDOW</STRONG>
       structure to be via functions  (see  <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>),  it
       makes functions of the common global variables, e.g., COL-
       ORS, COLOR_PAIRS, COLS, ESCDELAY, LINES,  TABSIZE  curscr,
       newscr  and  ttytype.   Those  variables are maintained as
       read-only values, stored in the <STRONG>SCREEN</STRONG> structure.

       Even this is not enough to make a thread-safe  application
       using  curses.   A multi-threaded application would be ex-
       pected to have threads updating separate  windows  (within
       the same device), or updating on separate screens (on dif-
       ferent devices).  Also, a few of the global variables  are
       considered  writable  by some applications.  The functions
       described here address these special situations.

       The ESCDELAY and TABSIZE global variables are modified  by
       some  applications.   To modify them in any configuration,
       use the  <STRONG>set_escdelay</STRONG>  or  <STRONG>set_tabsize</STRONG>  functions.   Other
       global variables are not modifiable.

       The  <STRONG>use_window</STRONG>  and  <STRONG>use_screen</STRONG>  functions provide coarse
       granularity mutexes for their respective <STRONG>WINDOW</STRONG> and <STRONG>SCREEN</STRONG>
       parameters,  and call a user-supplied function, passing it
       a <EM>data</EM> parameter, and returning the value from  the  user-
       supplied function to the application.

   <STRONG>USAGE</STRONG>
       All  of  the ncurses library functions assume that the lo-
       cale is not altered during operation.  In  addition,  they
       use data which is maintained within a hierarchy of scopes.

              -  global data, e.g., used in the low-level termin-
                 fo or termcap interfaces.

              -  terminal  data,  e.g., associated with a call to
                 <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>.  The terminal data are  initialized
                 when screens are created.

              -  screen  data,  e.g.,  associated  with a call to
                 <EM>newterm</EM> or <EM>initscr</EM>.

              -  window data, e.g., associated  with  a  call  to
                 <EM>newwin</EM>  or  <EM>subwin</EM>.  Windows are associated with
                 screens.  Pads are  not  necessarily  associated
                 with a particular screen.

                 Most  curses applications operate on one or more
                 windows within a single screen.

              -  reentrant, i.e., it uses only the data passed as
                 parameters.

       This table lists the scope of data used for each symbol in
       the ncurses library  when  it  is  configured  to  support
       threading:

      Symbol                  Scope
      -------------------------------------------------------------
      BC                      global
      COLORS                  screen (readonly)
      COLOR_PAIR              reentrant
      COLOR_PAIRS             screen (readonly)
      COLS                    screen (readonly)
      ESCDELAY                screen (readonly, see <EM>set</EM><STRONG>_</STRONG><EM>escdelay</EM>)
      LINES                   screen (readonly)
      PAIR_NUMBER             reentrant
      PC                      global
      SP                      global
      TABSIZE                 screen (readonly)
      UP                      global
      acs_map                 screen (readonly)
      add_wch                 window (stdscr)
      add_wchnstr             window (stdscr)
      add_wchstr              window (stdscr)
      addch                   window (stdscr)
      addchnstr               window (stdscr)
      addchstr                window (stdscr)
      addnstr                 window (stdscr)
      addnwstr                window (stdscr)
      addstr                  window (stdscr)
      addwstr                 window (stdscr)
      assume_default_colors   screen
      attr_get                window (stdscr)
      attr_off                window (stdscr)
      attr_on                 window (stdscr)
      attr_set                window (stdscr)
      attroff                 window (stdscr)
      attron                  window (stdscr)
      attrset                 window (stdscr)
      baudrate                screen
      beep                    screen
      bkgd                    window (stdscr)
      bkgdset                 window (stdscr)
      bkgrnd                  window (stdscr)
      bkgrndset               window (stdscr)
      boolcodes               global (readonly)
      boolfnames              global (readonly)
      boolnames               global (readonly)
      border                  window (stdscr)
      border_set              window (stdscr)
      box                     window (stdscr)
      box_set                 window (stdscr)

      can_change_color        terminal
      cbreak                  screen
      chgat                   window (stdscr)
      clear                   window (stdscr)
      clearok                 window
      clrtobot                window (stdscr)
      clrtoeol                window (stdscr)
      color_content           screen
      color_set               window (stdscr)
      copywin                 window locks(source, target)
      cur_term                terminal
      curs_set                screen
      curscr                  screen (readonly)
      curses_version          global (readonly)
      def_prog_mode           terminal
      def_shell_mode          terminal
      define_key              screen
      del_curterm             screen
      delay_output            screen
      delch                   window (stdscr)
      deleteln                window (stdscr)
      delscreen               global locks(screenlist, screen)
      delwin                  global locks(windowlist)
      derwin                  screen
      doupdate                screen
      dupwin                  screen locks(window)
      echo                    screen
      echo_wchar              window (stdscr)
      echochar                window (stdscr)
      endwin                  screen
      erase                   window (stdscr)
      erasechar               window (stdscr)
      erasewchar              window (stdscr)
      filter                  global
      flash                   terminal
      flushinp                screen
      get_wch                 screen (input-operation)
      get_wstr                screen (input-operation)
      getattrs                window
      getbegx                 window
      getbegy                 window
      getbkgd                 window
      getbkgrnd               window
      getcchar                reentrant
      getch                   screen (input-operation)
      getcurx                 window
      getcury                 window
      getmaxx                 window
      getmaxy                 window
      getmouse                screen (input-operation)
      getn_wstr               screen (input-operation)
      getnstr                 screen (input-operation)
      getparx                 window
      getpary                 window
      getstr                  screen (input-operation)
      getwin                  screen (input-operation)
      halfdelay               screen
      has_colors              terminal
      has_ic                  terminal
      has_il                  terminal
      has_key                 screen
      hline                   window (stdscr)
      hline_set               window (stdscr)
      idcok                   window
      idlok                   window
      immedok                 window

      in_wch                  window (stdscr)
      in_wchnstr              window (stdscr)
      in_wchstr               window (stdscr)
      inch                    window (stdscr)
      inchnstr                window (stdscr)
      inchstr                 window (stdscr)
      init_color              screen
      init_pair               screen
      initscr                 global locks(screenlist)
      innstr                  window (stdscr)
      innwstr                 window (stdscr)
      ins_nwstr               window (stdscr)
      ins_wch                 window (stdscr)
      ins_wstr                window (stdscr)
      insch                   window (stdscr)
      insdelln                window (stdscr)
      insertln                window (stdscr)
      insnstr                 window (stdscr)
      insstr                  window (stdscr)
      instr                   window (stdscr)
      intrflush               terminal
      inwstr                  window (stdscr)
      is_cleared              window
      is_idcok                window
      is_idlok                window
      is_immedok              window
      is_keypad               window
      is_leaveok              window
      is_linetouched          window
      is_nodelay              window
      is_notimeout            window
      is_scrollok             window
      is_syncok               window
      is_term_resized         terminal
      is_wintouched           window
      isendwin                screen
      key_defined             screen
      key_name                global (static data)
      keybound                screen
      keyname                 global (static data)
      keyok                   screen
      keypad                  window
      killchar                terminal
      killwchar               terminal
      leaveok                 window
      longname                screen
      mcprint                 terminal
      meta                    screen
      mouse_trafo             window (stdscr)
      mouseinterval           screen
      mousemask               screen
      move                    window (stdscr)
      mvadd_wch               window (stdscr)
      mvadd_wchnstr           window (stdscr)
      mvadd_wchstr            window (stdscr)
      mvaddch                 window (stdscr)
      mvaddchnstr             window (stdscr)
      mvaddchstr              window (stdscr)
      mvaddnstr               window (stdscr)
      mvaddnwstr              window (stdscr)
      mvaddstr                window (stdscr)
      mvaddwstr               window (stdscr)
      mvchgat                 window (stdscr)
      mvcur                   screen
      mvdelch                 window (stdscr)
      mvderwin                window (stdscr)

      mvget_wch               screen (input-operation)
      mvget_wstr              screen (input-operation)
      mvgetch                 screen (input-operation)
      mvgetn_wstr             screen (input-operation)
      mvgetnstr               screen (input-operation)
      mvgetstr                screen (input-operation)
      mvhline                 window (stdscr)
      mvhline_set             window (stdscr)
      mvin_wch                window (stdscr)
      mvin_wchnstr            window (stdscr)
      mvin_wchstr             window (stdscr)
      mvinch                  window (stdscr)
      mvinchnstr              window (stdscr)
      mvinchstr               window (stdscr)
      mvinnstr                window (stdscr)
      mvinnwstr               window (stdscr)
      mvins_nwstr             window (stdscr)
      mvins_wch               window (stdscr)
      mvins_wstr              window (stdscr)
      mvinsch                 window (stdscr)
      mvinsnstr               window (stdscr)
      mvinsstr                window (stdscr)
      mvinstr                 window (stdscr)
      mvinwstr                window (stdscr)
      mvprintw                window (stdscr)
      mvscanw                 screen
      mvvline                 window (stdscr)
      mvvline_set             window (stdscr)
      mvwadd_wch              window
      mvwadd_wchnstr          window
      mvwadd_wchstr           window
      mvwaddch                window
      mvwaddchnstr            window
      mvwaddchstr             window
      mvwaddnstr              window
      mvwaddnwstr             window
      mvwaddstr               window
      mvwaddwstr              window
      mvwchgat                window
      mvwdelch                window
      mvwget_wch              screen (input-operation)
      mvwget_wstr             screen (input-operation)
      mvwgetch                screen (input-operation)
      mvwgetn_wstr            screen (input-operation)
      mvwgetnstr              screen (input-operation)
      mvwgetstr               screen (input-operation)
      mvwhline                window
      mvwhline_set            window
      mvwin                   window
      mvwin_wch               window
      mvwin_wchnstr           window
      mvwin_wchstr            window
      mvwinch                 window
      mvwinchnstr             window
      mvwinchstr              window
      mvwinnstr               window
      mvwinnwstr              window
      mvwins_nwstr            window
      mvwins_wch              window
      mvwins_wstr             window
      mvwinsch                window
      mvwinsnstr              window
      mvwinsstr               window
      mvwinstr                window
      mvwinwstr               window
      mvwprintw               window

      mvwscanw                screen
      mvwvline                window
      mvwvline_set            window
      napms                   reentrant
      newpad                  global locks(windowlist)
      newscr                  screen (readonly)
      newterm                 global locks(screenlist)
      newwin                  global locks(windowlist)
      nl                      screen
      nocbreak                screen
      nodelay                 window
      noecho                  screen
      nofilter                global
      nonl                    screen
      noqiflush               terminal
      noraw                   screen
      notimeout               window
      numcodes                global (readonly)
      numfnames               global (readonly)
      numnames                global (readonly)
      ospeed                  global
      overlay                 window locks(source, target)
      overwrite               window locks(source, target)
      pair_content            screen
      pecho_wchar             screen
      pechochar               screen
      pnoutrefresh            screen
      prefresh                screen
      printw                  window
      putp                    global
      putwin                  window
      qiflush                 terminal
      raw                     screen
      redrawwin               window
      refresh                 screen
      reset_prog_mode         screen
      reset_shell_mode        screen
      resetty                 terminal
      resize_term             screen locks(windowlist)
      resizeterm              screen
      restartterm             screen
      ripoffline              global (static data)
      savetty                 terminal
      scanw                   screen
      scr_dump                screen
      scr_init                screen
      scr_restore             screen
      scr_set                 screen
      scrl                    window (stdscr)
      scroll                  window
      scrollok                window
      set_curterm             screen
      set_escdelay            screen
      set_tabsize             screen
      set_term                global locks(screenlist, screen)
      setcchar                reentrant
      setscrreg               window (stdscr)
      setupterm               global
      slk_attr                screen
      slk_attr_off            screen
      slk_attr_on             screen
      slk_attr_set            screen
      slk_attroff             screen
      slk_attron              screen
      slk_attrset             screen
      slk_clear               screen

      slk_color               screen
      slk_init                screen
      slk_label               screen
      slk_noutrefresh         screen
      slk_refresh             screen
      slk_restore             screen
      slk_set                 screen
      slk_touch               screen
      slk_wset                screen
      standend                window
      standout                window
      start_color             screen
      stdscr                  screen (readonly)
      strcodes                global (readonly)
      strfnames               global (readonly)
      strnames                global (readonly)
      subpad                  window
      subwin                  window
      syncok                  window
      term_attrs              screen
      termattrs               screen
      termname                terminal
      tgetent                 global
      tgetflag                global
      tgetnum                 global
      tgetstr                 global
      tgoto                   global
      tigetflag               terminal
      tigetnum                terminal
      tigetstr                terminal
      timeout                 window (stdscr)
      touchline               window
      touchwin                window
      tparm                   global (static data)
      tputs                   screen
      trace                   global (static data)
      ttytype                 screen (readonly)
      typeahead               screen
      unctrl                  screen
      unget_wch               screen (input-operation)
      ungetch                 screen (input-operation)
      ungetmouse              screen (input-operation)
      untouchwin              window
      use_default_colors      screen
      use_env                 global (static data)
      use_extended_names      global (static data)
      use_legacy_coding       screen
      use_screen              global locks(screenlist, screen)
      use_window              global locks(windowlist, window)
      vid_attr                screen
      vid_puts                screen
      vidattr                 screen
      vidputs                 screen
      vline                   window (stdscr)
      vline_set               window (stdscr)
      vw_printw               window
      vw_scanw                screen
      vwprintw                window
      vwscanw                 screen
      wadd_wch                window
      wadd_wchnstr            window
      wadd_wchstr             window
      waddch                  window
      waddchnstr              window
      waddchstr               window
      waddnstr                window

      waddnwstr               window
      waddstr                 window
      waddwstr                window
      wattr_get               window
      wattr_off               window
      wattr_on                window
      wattr_set               window
      wattroff                window
      wattron                 window
      wattrset                window
      wbkgd                   window
      wbkgdset                window
      wbkgrnd                 window
      wbkgrndset              window
      wborder                 window
      wborder_set             window
      wchgat                  window
      wclear                  window
      wclrtobot               window
      wclrtoeol               window
      wcolor_set              window
      wcursyncup              screen (affects window plus parents)
      wdelch                  window
      wdeleteln               window
      wecho_wchar             window
      wechochar               window
      wenclose                window
      werase                  window
      wget_wch                screen (input-operation)
      wget_wstr               screen (input-operation)
      wgetbkgrnd              window
      wgetch                  screen (input-operation)
      wgetn_wstr              screen (input-operation)
      wgetnstr                screen (input-operation)
      wgetparent              window
      wgetscrreg              window
      wgetstr                 screen (input-operation)
      whline                  window
      whline_set              window
      win_wch                 window
      win_wchnstr             window
      win_wchstr              window
      winch                   window
      winchnstr               window
      winchstr                window
      winnstr                 window
      winnwstr                window
      wins_nwstr              window
      wins_wch                window
      wins_wstr               window
      winsch                  window
      winsdelln               window
      winsertln               window
      winsnstr                window
      winsstr                 window
      winstr                  window
      winwstr                 window
      wmouse_trafo            window
      wmove                   window
      wnoutrefresh            screen
      wprintw                 window
      wredrawln               window
      wrefresh                screen
      wresize                 window locks(windowlist)
      wscanw                  screen
      wscrl                   window

      wsetscrreg              window
      wstandend               window
      wstandout               window
      wsyncdown               screen (affects window plus parents)
      wsyncup                 screen (affects window plus parents)
      wtimeout                window
      wtouchln                window
      wunctrl                 global (static data)
      wvline                  window
      wvline_set              window


</PRE>
<H2>RETURN VALUE</H2><PRE>
       These functions all return TRUE or FALSE, except as noted.


</PRE>
<H2>NOTES</H2><PRE>
       Both a macro and a function are provided for each name.


</PRE>
<H2>PORTABILITY</H2><PRE>
       These routines are specific to  ncurses.   They  were  not
       supported  on  Version 7, BSD or System V implementations.
       It is recommended that any code depending on  ncurses  ex-
       tensions be conditioned using NCURSES_VERSION.


</PRE>
<H2>SEE ALSO</H2><PRE>
       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>


                                                       <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>