Provided by: ncurses-doc_6.1-1ubuntu1.18.04.1_all bug

NAME

       curs_threads - 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 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)
                             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 extensions  be  conditioned  using
       NCURSES_VERSION.

SEE ALSO

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

                                                                                               threads(3NCURSES)