# curs_threads 3x 2023-10-07 ncurses 6.4 Library calls

    curs_threads(3x)                 Library calls                curs_threads(3x)

## NAME

           NCURSES_WINDOW_CB,   NCURSES_SCREEN_CB,   get_escdelay,   set_escdelay,
           set_tabsize, use_screen, use_window - curses support for multi-threaded
           applications

## SYNOPSIS

           #include <curses.h>

           /* data types */
           typedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
           typedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);

           int get_escdelay(void);
           int set_escdelay(int ms);
           int set_tabsize(int cols);

           int use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);
           int use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);

## DESCRIPTION

           The  ncurses  library  can  be  configured  to  support  multi-threaded
           applications in a  rudimentary  way.   Such  configuration  produces  a
           different set of libraries, named libncursest, for example, since doing
           so alters ncurses's application binary interface (ABI).

           Instead of modifying the programming interface (API)  to  make  ncurses
           functions  expect  an  additional  argument  specifying  a  thread, the
           library adds a few functions, usable in any  configuration,  that  hide
           the  mutexes  (mutual  exclusion  locks)  needed  to prevent concurrent
           access to variables shared by multiple threads of execution.

           ncurses threading support requires  the  use  of  functions  to  access
           members  of  the  WINDOW  structure  (see curs_opaque(3x)).  It further
           makes functions of the common  global  variables  COLORS,  COLOR_PAIRS,
           COLS,   ESCDELAY,   LINES,   TABSIZE,   curscr,  newscr,  and  ttytype,
           maintaining them as as read-only values in the SCREEN structure.

           Even this is not enough to make an  application  using  curses  thread-
           safe.   We  would  expect  a multi-threaded application to have threads
           updating separate windows (on the same device),  and  separate  screens
           (on  different  devices).   Further,  applications  expect a few of the
           global variables to be writable.  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.  get_escdelay retrieves ESCDELAY's value.

           The use_window and use_screen functions provide coarse-grained  mutexes
           for  their  respective  WINDOW and SCREEN parameters; they call a user-
           supplied function, pass it a data parameter, and return the value  from
           the user-supplied function to the application.

### Usage

           All  ncurses  library  functions  assume that the locale is not altered
           during operation.  In addition, they use data that is maintained within
           a hierarchy of scopes.

           o   global data used in the low-level terminfo or termcap interfaces

           o   terminal data associated with a call to set_curterm(3x)

               Terminal data are initialized when screens are created.

           o   screen data associated with a call to newterm(3x) or initscr(3x)

           o   window data associated with a call to newwin(3x) or subwin(3x)

               Windows  are  associated  with  screens.   Pads are not necessarily
               associated with any particular screen.

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

           o   reentrant  data  associated  with  "pure"  functions  that alter no
               shared variables

           The following table lists the scope  of  each  symbol  in  the  ncurses
           library when configured to support multi-threaded applications.

                Symbol                  Scope
                -------------------------------------------------------------
                BC                      global
                COLORS                  screen (read-only)
                COLOR_PAIR              reentrant
                COLOR_PAIRS             screen (read-only)
                COLS                    screen (read-only)
                ESCDELAY                screen (read-only; see set_escdelay)
                LINES                   screen (read-only)
                PAIR_NUMBER             reentrant
                PC                      global
                SP                      global
                TABSIZE                 screen (read-only; see set_tabsize)
                UP                      global
                acs_map                 screen (read-only)
                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 (read-only)
                boolfnames              global (read-only)
                boolnames               global (read-only)
                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 (read-only)
                curses_version          global (read-only)
                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 screen list, screen)
                delwin                  global (locks window list)
                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 screen list)
                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 window list)
                newscr                  screen (read-only)
                newterm                 global (locks screen list)
                newwin                  global (locks window list)
                nl                      screen
                nocbreak                screen
                nodelay                 window
                noecho                  screen
                nofilter                global
                nonl                    screen
                noqiflush               terminal
                noraw                   screen
                notimeout               window
                numcodes                global (read-only)
                numfnames               global (read-only)
                numnames                global (read-only)
                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 window list)
                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 screen list, 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 (read-only)
                strcodes                global (read-only)
                strfnames               global (read-only)
                strnames                global (read-only)
                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 (read-only)
                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 screen list, screen)
                use_window              global (locks window list, 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 window list)
                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

           get_escdelay   returns   the   value  of  ESCDELAY.   set_escdelay  and
           set_tabsize return ERR upon failure and OK upon successful  completion.
           use_screen  and use_window return the int returned by the user-supplied
           function they are called with.

## NOTES

           ncurses provides both a C function and a preprocessor  macro  for  each
           function documented in this page.

## 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

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

    ncurses 6.4                       2023-10-07                  curs_threads(3x)