# curs_threads 3x 2024-01-13 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 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                       2024-01-13                  curs_threads(3x)