aboutsummaryrefslogtreecommitdiff
path: root/man/curs_threads.3x
diff options
context:
space:
mode:
Diffstat (limited to 'man/curs_threads.3x')
-rw-r--r--man/curs_threads.3x603
1 files changed, 603 insertions, 0 deletions
diff --git a/man/curs_threads.3x b/man/curs_threads.3x
new file mode 100644
index 000000000000..17dabdb7b40a
--- /dev/null
+++ b/man/curs_threads.3x
@@ -0,0 +1,603 @@
+.\"***************************************************************************
+.\" Copyright (c) 2008 Free Software Foundation, Inc. *
+.\" *
+.\" Permission is hereby granted, free of charge, to any person obtaining a *
+.\" copy of this software and associated documentation files (the *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_threads.3x,v 1.12 2008/04/12 18:22:51 tom Exp $
+.TH curs_threads 3X ""
+.na
+.hy 0
+.SH NAME
+\fBuse_screen\fR,
+\fBuse_window\fR - \fBcurses\fR thread support
+.ad
+.hy
+.SH SYNOPSIS
+\fB#include <curses.h>\fR
+.sp
+\fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fR
+\fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fR
+.br
+\fBint set_escdelay(int size);\fR
+.br
+\fBint set_tabsize(int size);\fR
+.br
+\fBint use_screen(SCREEN *scr, NCURSES_WINDOW_CB func, void *data);\fR
+.br
+\fBint use_window(WINDOW *win, NCURSES_SCREEN_CB func, void *data);\fR
+.br
+.SH DESCRIPTION
+This implementation can be configured to provide rudimentary support
+for multi-threaded applications.
+This makes a different set of libraries, e.g., \fIlibncursest\fP since
+the binary interfaces are different.
+.PP
+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.
+.PP
+In addition to forcing access to members of the \fBWINDOW\fP structure
+to be via functions (see \fBcurs_opaque\fP(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 \fBSCREEN\fP
+structure.
+.PP
+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.
+.PP
+The ESCDELAY and TABSIZE global variables are modified by some applications.
+To modify them in any configuration,
+use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
+Other global variables are not modifiable.
+.PP
+The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
+granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
+parameters, and call a user-supplied function,
+passing it a \fIdata\fP parameter,
+and returning the value from the user-supplied function to the application.
+.\" ***************************************************************************
+.SS 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.
+.RS
+.TP 3
+-
+global data, e.g., used in the low-level terminfo or termcap interfaces.
+.TP 3
+-
+terminal data, e.g., associated with a call to \fIset_curterm\fP.
+The terminal data are initialized when screens are created.
+.TP 3
+-
+screen data, e.g., associated with a call to \fInewterm\fP or \fIinitscr\fP.
+.TP 3
+-
+window data, e.g., associated with a call to \fInewwin\fP or \fIsubwin\fP.
+Windows are associated with screens.
+Pads are not necessarily associated with a particular screen.
+.IP
+Most curses applications operate on one or more windows within a single screen.
+.TP 3
+-
+reentrant, i.e., it uses only the data passed as parameters.
+.RE
+.PP
+This table lists the scope of data used for each symbol in the
+ncurses library when it is configured to support threading:
+.TS
+center tab(/);
+l l
+l l .
+Symbol/Scope
+=
+BC/global
+COLORS/screen (readonly)
+COLOR_PAIR/reentrant
+COLOR_PAIRS/screen (readonly)
+COLS/screen (readonly)
+ESCDELAY/screen (readonly, see \fIset_escdelay\fP)
+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)
+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
+.TE
+.\" ***************************************************************************
+.SH RETURN VALUE
+These functions all return TRUE or FALSE, except as noted.
+.SH NOTES
+Both a macro and a function are provided for each name.
+.SH 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.
+.SH SEE ALSO
+\fBcurses\fR(3X),
+\fBcurs_opaque\fR(3X)
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End: