Provided by: ncurses-doc_6.4+20240113-1ubuntu2_all bug

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  opaque(3NCURSES)).   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.

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

       •   terminal data associated with a call to set_curterm(3NCURSES)

           Terminal data are initialized when screens are created.

       •   screen data associated with a call to newterm(3NCURSES) or initscr(3NCURSES)

       •   window data associated with a call to newwin(3NCURSES) or subwin(3NCURSES)

           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.

       •   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

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