+'\" t
.\"***************************************************************************
-.\" Copyright (c) 2008 Free Software Foundation, Inc. *
+.\" Copyright 2021-2023,2024 Thomas E. Dickey *
+.\" Copyright 2008-2015,2017 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_threads.3x,v 1.5 2008/03/29 20:28:12 tom Exp $
-.TH curs_threads 3X ""
-.na
-.hy 0
+.\" $Id: curs_threads.3x,v 1.56 2024/03/16 15:35:01 tom Exp $
+.TH curs_threads 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBuse_screen\fR,
-\fBuse_window\fR - \fBcurses\fR thread support
-.ad
-.hy
+\fI\%NCURSES_WINDOW_CB\fP,
+\fI\%NCURSES_SCREEN_CB\fP,
+\fB\%get_escdelay\fP,
+\fB\%set_escdelay\fP,
+\fB\%set_tabsize\fP,
+\fB\%use_screen\fP,
+\fB\%use_window\fP \-
+\fIcurses\fR support for multi-threaded applications
.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
+.nf
+\fB#include <curses.h>
+.PP
+\fI/* data types */
+\fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);
+\fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);
+.PP
+\fBint get_escdelay(void);
+\fBint set_escdelay(int \fIms\fP);
+\fBint set_tabsize(int \fIcols\fP);
+.PP
+\fBint use_screen(SCREEN *\fIscr\fP, NCURSES_SCREEN_CB \fIfunc\fP, void *\fIdata\fP);
+\fBint use_window(WINDOW *\fIwin\fP, NCURSES_WINDOW_CB \fIfunc\fP, void *\fIdata\fP);
+.fi
.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.
+The \fI\%ncurses\fP library can be configured to support multi-threaded
+applications in a rudimentary way.
+Such configuration produces a different set of libraries,
+named \fIlibncursest\fP,
+for example,
+since doing so alters \fI\%ncurses\fP's application binary interface
+(ABI).
.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.
+Instead of modifying the programming interface (API) to make
+\fI\%ncurses\fP functions expect an additional argument specifying a
+thread,
+the library adds functions,
+usable in any configuration,
+that hide the \fImutexes\fP
+(mutual exclusion locks)
+needed to prevent concurrent access to variables shared by multiple
+threads of execution.
.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.
+\fI\%ncurses\fP threading support requires the use of functions to
+access members of the \fI\%WINDOW\fP structure (see
+\fBcurs_opaque\fP(3X)).
+It further makes functions of the common global variables
+\fB\%COLORS\fP,
+\fB\%COLOR_PAIRS\fP,
+\fB\%COLS\fP,
+\fB\%ESCDELAY\fP,
+\fB\%LINES\fP,
+\fB\%TABSIZE\fP,
+\fB\%curscr\fP,
+\fB\%newscr\fP,
+and
+\fB\%ttytype\fP,
+maintaining them as as read-only values in the \fISCREEN\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.
+Even this is not enough to make an application using \fIcurses\fP
+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.
.PP
-The ESCDELAY and TABSIZE global variables are modified by some applications.
+The \fB\%ESCDELAY\fP and \fB\%TABSIZE\fP global variables are modified
+by some applications.
To modify them in any configuration,
-use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
+use the \fB\%set_escdelay\fP or \fB\%set_tabsize\fP functions.
Other global variables are not modifiable.
+\fBget_escdelay\fP retrieves \fB\%ESCDELAY\fP's value.
+.PP
+The \fBuse_window\fP and \fBuse_screen\fP functions provide
+coarse-grained mutexes for their respective \fI\%WINDOW\fP and
+\fISCREEN\fP parameters;
+they call a user-supplied function,
+pass it a \fIdata\fP parameter,
+and return the value from the user-supplied function to the application.
+.\" ***************************************************************************
+.SS Usage
+All \fI\%ncurses\fP library functions assume that the locale is not
+altered during operation.
+In addition,
+they use data that is maintained within a hierarchy of scopes.
+.bP
+global data used in the low-level \fIterminfo\fP or \fItermcap\fP
+interfaces
+.bP
+terminal data associated with a call to \fBset_curterm\fP(3X)
+.IP
+Terminal data are initialized when screens are created.
+.bP
+screen data associated with a call to \fBnewterm\fP(3X) or
+\fBinitscr\fP(3X)
+.bP
+window data associated with a call to \fBnewwin\fP(3X) or
+\fBsubwin\fP(3X)
+.IP
+Windows are associated with screens.
+Pads are not necessarily associated with any particular screen.
+.IP
+Most \fIcurses\fP applications operate on one or more windows within a
+single screen.
+.bP
+reentrant data associated with \*(``pure\*('' functions that alter no
+shared variables
+.PP
+The following table lists the scope of each symbol in the
+\fI\%ncurses\fP library when configured to support multi-threaded
+applications.
.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.
+.TS
+center;
+Lb2 Lb
+Lb2 Lx.
+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 \fBset_escdelay\fP)
+LINES screen (read-only)
+PAIR_NUMBER reentrant
+PC global
+SP global
+TABSIZE screen (read-only; see \fBset_tabsize\fP)
+UP global
+acs_map screen (read-only)
+add_wch window (\fBstdscr\fP)
+add_wchnstr window (\fBstdscr\fP)
+add_wchstr window (\fBstdscr\fP)
+addch window (\fBstdscr\fP)
+addchnstr window (\fBstdscr\fP)
+addchstr window (\fBstdscr\fP)
+addnstr window (\fBstdscr\fP)
+addnwstr window (\fBstdscr\fP)
+addstr window (\fBstdscr\fP)
+addwstr window (\fBstdscr\fP)
+assume_default_colors screen
+attr_get window (\fBstdscr\fP)
+attr_off window (\fBstdscr\fP)
+attr_on window (\fBstdscr\fP)
+attr_set window (\fBstdscr\fP)
+attroff window (\fBstdscr\fP)
+attron window (\fBstdscr\fP)
+attrset window (\fBstdscr\fP)
+baudrate screen
+beep screen
+bkgd window (\fBstdscr\fP)
+bkgdset window (\fBstdscr\fP)
+bkgrnd window (\fBstdscr\fP)
+bkgrndset window (\fBstdscr\fP)
+boolcodes global (read-only)
+boolfnames global (read-only)
+boolnames global (read-only)
+border window (\fBstdscr\fP)
+border_set window (\fBstdscr\fP)
+box window (\fBstdscr\fP)
+box_set window (\fBstdscr\fP)
+can_change_color terminal
+cbreak screen
+chgat window (\fBstdscr\fP)
+clear window (\fBstdscr\fP)
+clearok window
+clrtobot window (\fBstdscr\fP)
+clrtoeol window (\fBstdscr\fP)
+color_content screen
+color_set window (\fBstdscr\fP)
+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 (\fBstdscr\fP)
+deleteln window (\fBstdscr\fP)
+delscreen global (locks screen list, screen)
+delwin global (locks window list)
+derwin screen
+doupdate screen
+dupwin screen (locks window)
+echo screen
+echo_wchar window (\fBstdscr\fP)
+echochar window (\fBstdscr\fP)
+endwin screen
+erase window (\fBstdscr\fP)
+erasechar window (\fBstdscr\fP)
+erasewchar window (\fBstdscr\fP)
+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 (\fBstdscr\fP)
+hline_set window (\fBstdscr\fP)
+idcok window
+idlok window
+immedok window
+in_wch window (\fBstdscr\fP)
+in_wchnstr window (\fBstdscr\fP)
+in_wchstr window (\fBstdscr\fP)
+inch window (\fBstdscr\fP)
+inchnstr window (\fBstdscr\fP)
+inchstr window (\fBstdscr\fP)
+init_color screen
+init_pair screen
+initscr global (locks screen list)
+innstr window (\fBstdscr\fP)
+innwstr window (\fBstdscr\fP)
+ins_nwstr window (\fBstdscr\fP)
+ins_wch window (\fBstdscr\fP)
+ins_wstr window (\fBstdscr\fP)
+insch window (\fBstdscr\fP)
+insdelln window (\fBstdscr\fP)
+insertln window (\fBstdscr\fP)
+insnstr window (\fBstdscr\fP)
+insstr window (\fBstdscr\fP)
+instr window (\fBstdscr\fP)
+intrflush terminal
+inwstr window (\fBstdscr\fP)
+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 (\fBstdscr\fP)
+mouseinterval screen
+mousemask screen
+move window (\fBstdscr\fP)
+mvadd_wch window (\fBstdscr\fP)
+mvadd_wchnstr window (\fBstdscr\fP)
+mvadd_wchstr window (\fBstdscr\fP)
+mvaddch window (\fBstdscr\fP)
+mvaddchnstr window (\fBstdscr\fP)
+mvaddchstr window (\fBstdscr\fP)
+mvaddnstr window (\fBstdscr\fP)
+mvaddnwstr window (\fBstdscr\fP)
+mvaddstr window (\fBstdscr\fP)
+mvaddwstr window (\fBstdscr\fP)
+mvchgat window (\fBstdscr\fP)
+mvcur screen
+mvdelch window (\fBstdscr\fP)
+mvderwin window (\fBstdscr\fP)
+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 (\fBstdscr\fP)
+mvhline_set window (\fBstdscr\fP)
+mvin_wch window (\fBstdscr\fP)
+mvin_wchnstr window (\fBstdscr\fP)
+mvin_wchstr window (\fBstdscr\fP)
+mvinch window (\fBstdscr\fP)
+mvinchnstr window (\fBstdscr\fP)
+mvinchstr window (\fBstdscr\fP)
+mvinnstr window (\fBstdscr\fP)
+mvinnwstr window (\fBstdscr\fP)
+mvins_nwstr window (\fBstdscr\fP)
+mvins_wch window (\fBstdscr\fP)
+mvins_wstr window (\fBstdscr\fP)
+mvinsch window (\fBstdscr\fP)
+mvinsnstr window (\fBstdscr\fP)
+mvinsstr window (\fBstdscr\fP)
+mvinstr window (\fBstdscr\fP)
+mvinwstr window (\fBstdscr\fP)
+mvprintw window (\fBstdscr\fP)
+mvscanw screen
+mvvline window (\fBstdscr\fP)
+mvvline_set window (\fBstdscr\fP)
+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 (\fBstdscr\fP)
+scroll window
+scrollok window
+set_curterm screen
+set_escdelay screen
+set_tabsize screen
+set_term global (locks screen list, screen)
+setcchar reentrant
+setscrreg window (\fBstdscr\fP)
+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
+\fBstdscr\fP 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 (\fBstdscr\fP)
+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 (\fBstdscr\fP)
+vline_set window (\fBstdscr\fP)
+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
+.TE
+.\" ***************************************************************************
.SH RETURN VALUE
-These functions all return TRUE or FALSE, except as noted.
+\fB\%get_escdelay\fP returns the value of \fB\%ESCDELAY\fP.
+\fB\%set_escdelay\fP and \fB\%set_tabsize\fP return \fBERR\fP upon
+failure and \fBOK\fP upon successful completion.
+\fB\%use_screen\fP and \fB\%use_window\fP return the \fIint\fP returned
+by the user-supplied function they are called with.
.SH NOTES
-Both a macro and a function are provided for each name.
+\fI\%ncurses\fP provides both a C function and a preprocessor macro for
+each function documented in this page.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
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.
+It is recommended that any code depending on \fI\%ncurses\fP extensions
+be conditioned using \fB\%NCURSES_VERSION\fP.
.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:
+\fB\%curses\fP(3X),
+\fB\%curs_opaque\fP(3X),
+\fB\%curs_variables\fP(3X)
projects / ncurses.git / blobdiff