https://invisible-island.net/ncurses/man/


curs_threads 3x 2024-03-16 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-03-16                  curs_threads(3x)