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_SCREEN_CB func, void
       *data);
       int use_window(WINDOW *win, NCURSES_WINDOW_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)
      wgetdelay               window
      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)