curs_threads 3x

curs_threads(3x)                                              curs_threads(3x)




NAME

       curs_threads - curses thread support


SYNOPSIS

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

       This  implementation  can  be configured to provide rudimentary support
       for multi-threaded applications.  This makes a  different  set  of  li-
       braries, 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  configura-
       tion  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 applica-
       tions.  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 mu-
       texes for their respective WINDOW and SCREEN parameters, and call a us-
       er-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  al-
       tered during operation.  In addition, they use data which is maintained
       within a hierarchy of scopes.

          o   global data, e.g., used in the low-level terminfo or termcap in-
              terfaces.

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

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

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

          o   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

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


NOTES

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


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


SEE ALSO

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



                                                              curs_threads(3x)