NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | PORTABILITY | SEE ALSO | COLOPHON

curs_threads(3X)                                            curs_threads(3X)

NAME         top

       curs_threads - curses thread support

SYNOPSIS         top

       #include <curses.h>

       typedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
       typedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);
       int get_escdelay(void);
       int set_escdelay(int size);
       int set_tabsize(int size);
       int use_screen(SCREEN *scr, NCURSES_SCREEN_CB func, void *data);
       int use_window(WINDOW *win, NCURSES_WINDOW_CB func, void *data);

DESCRIPTION         top

       This implementation can be configured to provide rudimentary support
       for multi-threaded applications.  This makes a different set of
       libraries, e.g., libncursest since the binary interfaces are
       different.

       Rather than modify the interfaces to pass a thread specifier to each
       function, it adds a few functions which can be used in any
       configuration which hide the mutex's needed to prevent concurrent use
       of the global variables when configured for threading.

       In addition to forcing access to members of the WINDOW structure to
       be via functions (see curs_opaque(3X)), it makes functions of the
       common global variables, e.g., COLORS, COLOR_PAIRS, COLS, ESCDELAY,
       LINES, TABSIZE curscr, newscr and ttytype.  Those variables are
       maintained as read-only values, stored in the SCREEN structure.

       Even this is not enough to make a thread-safe application using
       curses.  A multi-threaded application would be expected to have
       threads updating separate windows (within the same device), or
       updating on separate screens (on different devices).  Also, a few of
       the global variables are considered writable by some applications.
       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.

       The get_escdelay function returns the value for ESCDELAY.

       The use_window and use_screen functions provide coarse granularity
       mutexes for their respective WINDOW and SCREEN parameters, and call a
       user-supplied function, passing it a data parameter, and returning
       the value from the user-supplied function to the application.

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

          ·   global data, e.g., used in the low-level terminfo or termcap
              interfaces.

          ·   terminal data, e.g., associated with a call to set_curterm.
              The terminal data are initialized when screens are created.

          ·   screen data, e.g., associated with a call to newterm or
              initscr.

          ·   window data, e.g., associated with a call to newwin or subwin.
              Windows are associated with screens.  Pads are not necessarily
              associated with a particular screen.

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

          ·   reentrant, i.e., it uses only the data passed as parameters.

       This table lists the scope of data used for each symbol in the
       ncurses library when it is configured to support threading:

           Symbol                  Scope
           ─────────────────────────────────────────────────────────────
           BC                      global
           COLORS                  screen (readonly)
           COLOR_PAIR              reentrant
           COLOR_PAIRS             screen (readonly)
           COLS                    screen (readonly)
           ESCDELAY                screen (readonly, see set_escdelay)
           LINES                   screen (readonly)
           PAIR_NUMBER             reentrant
           PC                      global
           SP                      global
           TABSIZE                 screen (readonly)
           UP                      global
           acs_map                 screen (readonly)
           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 (readonly)
           boolfnames              global (readonly)
           boolnames               global (readonly)
           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 (readonly)
           curses_version          global (readonly)
           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(screenlist, screen)
           delwin                  global locks(windowlist)
           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(screenlist)
           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(windowlist)
           newscr                  screen (readonly)
           newterm                 global locks(screenlist)

           newwin                  global locks(windowlist)
           nl                      screen
           nocbreak                screen
           nodelay                 window
           noecho                  screen
           nofilter                global
           nonl                    screen
           noqiflush               terminal
           noraw                   screen
           notimeout               window
           numcodes                global (readonly)
           numfnames               global (readonly)
           numnames                global (readonly)
           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(windowlist)
           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(screenlist, 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 (readonly)
           strcodes                global (readonly)
           strfnames               global (readonly)
           strnames                global (readonly)
           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 (readonly)
           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(screenlist, screen)
           use_window              global locks(windowlist, 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(windowlist)
           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         top

       These functions all return TRUE or FALSE, except as noted.

NOTES         top

       Both a macro and a function are provided for each name.

PORTABILITY         top

       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         top

       curses(3X), curs_opaque(3X), curs_variables(3X).

COLOPHON         top

       This page is part of the ncurses (new curses) project.  Information
       about the project can be found at 
       ⟨https://www.gnu.org/software/ncurses/ncurses.html⟩.  If you have a
       bug report for this manual page, send it to
       bug-ncurses-request@gnu.org.  This page was obtained from the
       project's upstream Git mirror of the CVS repository 
       ⟨git://ncurses.scripts.mit.edu/ncurses.git⟩ on 2017-07-05.  If you
       discover any rendering problems in this HTML version of the page, or
       you believe there is a better or more up-to-date source for the page,
       or you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

                                                            curs_threads(3X)