Provided by: ncurses-doc_5.9-4_all bug

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 rudimentary 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 specifier 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.,  COLORS,
       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 expected to have threads updating separate windows (within the same
       device), or updating on separate screens (on different  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  locale 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 terminfo 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 extensions
       be conditioned using NCURSES_VERSION.

SEE ALSO

       ncurses(3NCURSES), opaque(3NCURSES), curses_variables(3NCURSES).

                                                                                threads(3NCURSES)