# curs_threads 3x

    curs_threads(3x)                                       curs_threads(3x)

## NAME

           use_screen, use_window - curses thread support

## SYNOPSIS

           #include <curses.h>

           typedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
           typedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);
           int get_escdelay(void);
           int set_escdelay(int size);
           int set_tabsize(int size);
           int  use_screen(SCREEN  *scr, NCURSES_WINDOW_CB func, void
           *data);
           int use_window(WINDOW *win, NCURSES_SCREEN_CB  func,  void
           *data);

## DESCRIPTION

           This  implementation can be configured to provide rudimen-
           tary support for multi-threaded applications.  This  makes
           a  different set of libraries, e.g., libncursest 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  WINDOW
           structure  to  be  via functions (see curs_opaque(3x)), 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 SCREEN 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  set_escdelay  or  set_tabsize  functions.  Other
           global variables are not modifiable.

           The get_escdelay function returns the value for ESCDELAY.

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

       USAGE
           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.

              o   global data, e.g., used in the  low-level  terminfo
                  or termcap interfaces.

              o   terminal  data,  e.g.,  associated  with  a call to
                  set_curterm.  The  terminal  data  are  initialized
                  when screens are created.

              o   screen  data,  e.g.,  associated  with  a  call  to
                  newterm or initscr.

              o   window data, e.g., associated with a call to newwin
                  or  subwin.   Windows  are associated with screens.
                  Pads are not necessarily associated with a particu-
                  lar screen.

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

              o   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 set_escdelay)
          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

## RETURN VALUE

           These functions all return TRUE or FALSE, except as noted.

## NOTES

           Both a macro and a function are provided for each name.

## PORTABILITY

           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.

## SEE ALSO

           curses(3x), curs_opaque(3x), curs_variables(3x).

                                                           curs_threads(3x)