curs_threads 3x 2023-11-25 ncurses 6.4 Library calls

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


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


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


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


       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


       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.


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


       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


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

ncurses 6.4                       2023-11-25                  curs_threads(3x)