# 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 *); type-
           def int (*NCURSES_SCREEN_CB)(SCREEN *, 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  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.

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

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

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

                  -  window data, e.g., associated  with  a  call  to
                     newwin  or  subwin.  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 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_threads(3x)