jcs.org
jcs's openbsd hax
openbsd
1'\" t
2.\"***************************************************************************
3.\" Copyright 2021-2022,2023 Thomas E. Dickey *
4.\" Copyright 2008-2015,2017 Free Software Foundation, Inc. *
5.\" *
6.\" Permission is hereby granted, free of charge, to any person obtaining a *
7.\" copy of this software and associated documentation files (the *
8.\" "Software"), to deal in the Software without restriction, including *
9.\" without limitation the rights to use, copy, modify, merge, publish, *
10.\" distribute, distribute with modifications, sublicense, and/or sell *
11.\" copies of the Software, and to permit persons to whom the Software is *
12.\" furnished to do so, subject to the following conditions: *
13.\" *
14.\" The above copyright notice and this permission notice shall be included *
15.\" in all copies or substantial portions of the Software. *
16.\" *
17.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24.\" *
25.\" Except as contained in this notice, the name(s) of the above copyright *
26.\" holders shall not be used in advertising or otherwise to promote the *
27.\" sale, use or other dealings in this Software without prior written *
28.\" authorization. *
29.\"***************************************************************************
30.\"
31.\" $Id: curs_threads.3,v 1.1 2023/10/17 09:52:08 nicm Exp $
32.TH curs_threads 3 2023-08-19 "ncurses 6.4" "Library calls"
33.de bP
34.ie n .IP \(bu 4
35.el .IP \(bu 2
36..
37.na
38.hy 0
39.SH NAME
40\fBcurs_threads\fP \- \fBcurses\fP thread support
41.ad
42.hy
43.SH SYNOPSIS
44\fB#include <curses.h>\fP
45.sp
46\fBtypedef int (*NCURSES_WINDOW_CB)(WINDOW *, void *);\fP
47.br
48\fBtypedef int (*NCURSES_SCREEN_CB)(SCREEN *, void *);\fP
49.sp
50\fBint get_escdelay(void);\fP
51.br
52\fBint set_escdelay(int \fIms\fB);\fR
53.br
54\fBint set_tabsize(int \fIcols\fB);\fR
55.sp
56\fBint use_screen(SCREEN *\fIscr\fB, NCURSES_SCREEN_CB \fIfunc\fB, void *\fIdata\fB);\fR
57.br
58\fBint use_window(WINDOW *\fIwin\fB, NCURSES_WINDOW_CB \fIfunc\fB, void *\fIdata\fB);\fR
59.SH DESCRIPTION
60This implementation can be configured to provide rudimentary support
61for multi-threaded applications.
62This makes a different set of libraries, e.g., \fBlibncursest\fP since
63the binary interfaces are different.
64.PP
65Rather than modify the interfaces to pass a thread specifier to
66each function, it adds a few functions which can be used in any
67configuration which hide the mutex's needed to prevent concurrent
68use of the global variables when configured for threading.
69.PP
70In addition to forcing access to members of the \fBWINDOW\fP structure
71to be via functions (see \fBcurs_opaque\fP(3)),
72it makes functions of the common global variables,
73e.g.,
74COLORS,
75COLOR_PAIRS,
76COLS,
77ESCDELAY,
78LINES,
79TABSIZE
80curscr,
81newscr and
82ttytype.
83Those variables are maintained as read-only values, stored in the \fBSCREEN\fP
84structure.
85.PP
86Even this is not enough to make a thread-safe application using curses.
87A multi-threaded application would be expected to have threads updating
88separate windows (within the same device),
89or updating on separate screens (on different devices).
90Also, a few of the global variables are considered writable by some
91applications.
92The functions described here address these special situations.
93.PP
94The ESCDELAY and TABSIZE global variables are modified by some applications.
95To modify them in any configuration,
96use the \fBset_escdelay\fP or \fBset_tabsize\fP functions.
97Other global variables are not modifiable.
98.PP
99The \fBget_escdelay\fP function returns the value for ESCDELAY.
100.PP
101The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse
102granularity mutexes for their respective \fBWINDOW\fP and \fBSCREEN\fP
103parameters, and call a user-supplied function,
104passing it a \fIdata\fP parameter,
105and returning the value from the user-supplied function to the application.
106.\" ***************************************************************************
107.SS USAGE
108All of the ncurses library functions assume that the locale is not
109altered during operation.
110In addition,
111they use data which is maintained within a hierarchy of scopes.
112.RS 3
113.bP
114global data, e.g., used in the low-level terminfo or termcap interfaces.
115.bP
116terminal data, e.g., associated with a call to \fBset_curterm\fP.
117The terminal data are initialized when screens are created.
118.bP
119screen data, e.g., associated with a call to \fBnewterm\fP or \fBinitscr\fP.
120.bP
121window data, e.g., associated with a call to \fBnewwin\fP or \fBsubwin\fP.
122Windows are associated with screens.
123Pads are not necessarily associated with a particular screen.
124.IP
125Most curses applications operate on one or more windows within a single screen.
126.bP
127reentrant, i.e., it uses only the data passed as parameters.
128.RE
129.PP
130This table lists the scope of data used for each symbol in the
131ncurses library when it is configured to support threading:
132.PP
133.TS
134center tab(/);
135l l
136l l .
137Symbol/Scope
138=
139BC/global
140COLORS/screen (readonly)
141COLOR_PAIR/reentrant
142COLOR_PAIRS/screen (readonly)
143COLS/screen (readonly)
144ESCDELAY/screen (readonly, see \fBset_escdelay\fP)
145LINES/screen (readonly)
146PAIR_NUMBER/reentrant
147PC/global
148SP/global
149TABSIZE/screen (readonly)
150UP/global
151acs_map/screen (readonly)
152add_wch/window (stdscr)
153add_wchnstr/window (stdscr)
154add_wchstr/window (stdscr)
155addch/window (stdscr)
156addchnstr/window (stdscr)
157addchstr/window (stdscr)
158addnstr/window (stdscr)
159addnwstr/window (stdscr)
160addstr/window (stdscr)
161addwstr/window (stdscr)
162assume_default_colors/screen
163attr_get/window (stdscr)
164attr_off/window (stdscr)
165attr_on/window (stdscr)
166attr_set/window (stdscr)
167attroff/window (stdscr)
168attron/window (stdscr)
169attrset/window (stdscr)
170baudrate/screen
171beep/screen
172bkgd/window (stdscr)
173bkgdset/window (stdscr)
174bkgrnd/window (stdscr)
175bkgrndset/window (stdscr)
176boolcodes/global (readonly)
177boolfnames/global (readonly)
178boolnames/global (readonly)
179border/window (stdscr)
180border_set/window (stdscr)
181box/window (stdscr)
182box_set/window (stdscr)
183can_change_color/terminal
184cbreak/screen
185chgat/window (stdscr)
186clear/window (stdscr)
187clearok/window
188clrtobot/window (stdscr)
189clrtoeol/window (stdscr)
190color_content/screen
191color_set/window (stdscr)
192copywin/window locks(source, target)
193cur_term/terminal
194curs_set/screen
195curscr/screen (readonly)
196curses_version/global (readonly)
197def_prog_mode/terminal
198def_shell_mode/terminal
199define_key/screen
200del_curterm/screen
201delay_output/screen
202delch/window (stdscr)
203deleteln/window (stdscr)
204delscreen/global locks(screenlist, screen)
205delwin/global locks(windowlist)
206derwin/screen
207doupdate/screen
208dupwin/screen locks(window)
209echo/screen
210echo_wchar/window (stdscr)
211echochar/window (stdscr)
212endwin/screen
213erase/window (stdscr)
214erasechar/window (stdscr)
215erasewchar/window (stdscr)
216filter/global
217flash/terminal
218flushinp/screen
219get_wch/screen (input-operation)
220get_wstr/screen (input-operation)
221getattrs/window
222getbegx/window
223getbegy/window
224getbkgd/window
225getbkgrnd/window
226getcchar/reentrant
227getch/screen (input-operation)
228getcurx/window
229getcury/window
230getmaxx/window
231getmaxy/window
232getmouse/screen (input-operation)
233getn_wstr/screen (input-operation)
234getnstr/screen (input-operation)
235getparx/window
236getpary/window
237getstr/screen (input-operation)
238getwin/screen (input-operation)
239halfdelay/screen
240has_colors/terminal
241has_ic/terminal
242has_il/terminal
243has_key/screen
244hline/window (stdscr)
245hline_set/window (stdscr)
246idcok/window
247idlok/window
248immedok/window
249in_wch/window (stdscr)
250in_wchnstr/window (stdscr)
251in_wchstr/window (stdscr)
252inch/window (stdscr)
253inchnstr/window (stdscr)
254inchstr/window (stdscr)
255init_color/screen
256init_pair/screen
257initscr/global locks(screenlist)
258innstr/window (stdscr)
259innwstr/window (stdscr)
260ins_nwstr/window (stdscr)
261ins_wch/window (stdscr)
262ins_wstr/window (stdscr)
263insch/window (stdscr)
264insdelln/window (stdscr)
265insertln/window (stdscr)
266insnstr/window (stdscr)
267insstr/window (stdscr)
268instr/window (stdscr)
269intrflush/terminal
270inwstr/window (stdscr)
271is_cleared/window
272is_idcok/window
273is_idlok/window
274is_immedok/window
275is_keypad/window
276is_leaveok/window
277is_linetouched/window
278is_nodelay/window
279is_notimeout/window
280is_scrollok/window
281is_syncok/window
282is_term_resized/terminal
283is_wintouched/window
284isendwin/screen
285key_defined/screen
286key_name/global (static data)
287keybound/screen
288keyname/global (static data)
289keyok/screen
290keypad/window
291killchar/terminal
292killwchar/terminal
293leaveok/window
294longname/screen
295mcprint/terminal
296meta/screen
297mouse_trafo/window (stdscr)
298mouseinterval/screen
299mousemask/screen
300move/window (stdscr)
301mvadd_wch/window (stdscr)
302mvadd_wchnstr/window (stdscr)
303mvadd_wchstr/window (stdscr)
304mvaddch/window (stdscr)
305mvaddchnstr/window (stdscr)
306mvaddchstr/window (stdscr)
307mvaddnstr/window (stdscr)
308mvaddnwstr/window (stdscr)
309mvaddstr/window (stdscr)
310mvaddwstr/window (stdscr)
311mvchgat/window (stdscr)
312mvcur/screen
313mvdelch/window (stdscr)
314mvderwin/window (stdscr)
315mvget_wch/screen (input-operation)
316mvget_wstr/screen (input-operation)
317mvgetch/screen (input-operation)
318mvgetn_wstr/screen (input-operation)
319mvgetnstr/screen (input-operation)
320mvgetstr/screen (input-operation)
321mvhline/window (stdscr)
322mvhline_set/window (stdscr)
323mvin_wch/window (stdscr)
324mvin_wchnstr/window (stdscr)
325mvin_wchstr/window (stdscr)
326mvinch/window (stdscr)
327mvinchnstr/window (stdscr)
328mvinchstr/window (stdscr)
329mvinnstr/window (stdscr)
330mvinnwstr/window (stdscr)
331mvins_nwstr/window (stdscr)
332mvins_wch/window (stdscr)
333mvins_wstr/window (stdscr)
334mvinsch/window (stdscr)
335mvinsnstr/window (stdscr)
336mvinsstr/window (stdscr)
337mvinstr/window (stdscr)
338mvinwstr/window (stdscr)
339mvprintw/window (stdscr)
340mvscanw/screen
341mvvline/window (stdscr)
342mvvline_set/window (stdscr)
343mvwadd_wch/window
344mvwadd_wchnstr/window
345mvwadd_wchstr/window
346mvwaddch/window
347mvwaddchnstr/window
348mvwaddchstr/window
349mvwaddnstr/window
350mvwaddnwstr/window
351mvwaddstr/window
352mvwaddwstr/window
353mvwchgat/window
354mvwdelch/window
355mvwget_wch/screen (input-operation)
356mvwget_wstr/screen (input-operation)
357mvwgetch/screen (input-operation)
358mvwgetn_wstr/screen (input-operation)
359mvwgetnstr/screen (input-operation)
360mvwgetstr/screen (input-operation)
361mvwhline/window
362mvwhline_set/window
363mvwin/window
364mvwin_wch/window
365mvwin_wchnstr/window
366mvwin_wchstr/window
367mvwinch/window
368mvwinchnstr/window
369mvwinchstr/window
370mvwinnstr/window
371mvwinnwstr/window
372mvwins_nwstr/window
373mvwins_wch/window
374mvwins_wstr/window
375mvwinsch/window
376mvwinsnstr/window
377mvwinsstr/window
378mvwinstr/window
379mvwinwstr/window
380mvwprintw/window
381mvwscanw/screen
382mvwvline/window
383mvwvline_set/window
384napms/reentrant
385newpad/global locks(windowlist)
386newscr/screen (readonly)
387newterm/global locks(screenlist)
388newwin/global locks(windowlist)
389nl/screen
390nocbreak/screen
391nodelay/window
392noecho/screen
393nofilter/global
394nonl/screen
395noqiflush/terminal
396noraw/screen
397notimeout/window
398numcodes/global (readonly)
399numfnames/global (readonly)
400numnames/global (readonly)
401ospeed/global
402overlay/window locks(source, target)
403overwrite/window locks(source, target)
404pair_content/screen
405pecho_wchar/screen
406pechochar/screen
407pnoutrefresh/screen
408prefresh/screen
409printw/window
410putp/global
411putwin/window
412qiflush/terminal
413raw/screen
414redrawwin/window
415refresh/screen
416reset_prog_mode/screen
417reset_shell_mode/screen
418resetty/terminal
419resize_term/screen locks(windowlist)
420resizeterm/screen
421restartterm/screen
422ripoffline/global (static data)
423savetty/terminal
424scanw/screen
425scr_dump/screen
426scr_init/screen
427scr_restore/screen
428scr_set/screen
429scrl/window (stdscr)
430scroll/window
431scrollok/window
432set_curterm/screen
433set_escdelay/screen
434set_tabsize/screen
435set_term/global locks(screenlist, screen)
436setcchar/reentrant
437setscrreg/window (stdscr)
438setupterm/global
439slk_attr/screen
440slk_attr_off/screen
441slk_attr_on/screen
442slk_attr_set/screen
443slk_attroff/screen
444slk_attron/screen
445slk_attrset/screen
446slk_clear/screen
447slk_color/screen
448slk_init/screen
449slk_label/screen
450slk_noutrefresh/screen
451slk_refresh/screen
452slk_restore/screen
453slk_set/screen
454slk_touch/screen
455slk_wset/screen
456standend/window
457standout/window
458start_color/screen
459stdscr/screen (readonly)
460strcodes/global (readonly)
461strfnames/global (readonly)
462strnames/global (readonly)
463subpad/window
464subwin/window
465syncok/window
466term_attrs/screen
467termattrs/screen
468termname/terminal
469tgetent/global
470tgetflag/global
471tgetnum/global
472tgetstr/global
473tgoto/global
474tigetflag/terminal
475tigetnum/terminal
476tigetstr/terminal
477timeout/window (stdscr)
478touchline/window
479touchwin/window
480tparm/global (static data)
481tputs/screen
482trace/global (static data)
483ttytype/screen (readonly)
484typeahead/screen
485unctrl/screen
486unget_wch/screen (input-operation)
487ungetch/screen (input-operation)
488ungetmouse/screen (input-operation)
489untouchwin/window
490use_default_colors/screen
491use_env/global (static data)
492use_extended_names/global (static data)
493use_legacy_coding/screen
494use_screen/global locks(screenlist, screen)
495use_window/global locks(windowlist, window)
496vid_attr/screen
497vid_puts/screen
498vidattr/screen
499vidputs/screen
500vline/window (stdscr)
501vline_set/window (stdscr)
502vw_printw/window
503vw_scanw/screen
504vwprintw/window
505vwscanw/screen
506wadd_wch/window
507wadd_wchnstr/window
508wadd_wchstr/window
509waddch/window
510waddchnstr/window
511waddchstr/window
512waddnstr/window
513waddnwstr/window
514waddstr/window
515waddwstr/window
516wattr_get/window
517wattr_off/window
518wattr_on/window
519wattr_set/window
520wattroff/window
521wattron/window
522wattrset/window
523wbkgd/window
524wbkgdset/window
525wbkgrnd/window
526wbkgrndset/window
527wborder/window
528wborder_set/window
529wchgat/window
530wclear/window
531wclrtobot/window
532wclrtoeol/window
533wcolor_set/window
534wcursyncup/screen (affects window plus parents)
535wdelch/window
536wdeleteln/window
537wecho_wchar/window
538wechochar/window
539wenclose/window
540werase/window
541wget_wch/screen (input-operation)
542wget_wstr/screen (input-operation)
543wgetbkgrnd/window
544wgetch/screen (input-operation)
545wgetdelay/window
546wgetn_wstr/screen (input-operation)
547wgetnstr/screen (input-operation)
548wgetparent/window
549wgetscrreg/window
550wgetstr/screen (input-operation)
551whline/window
552whline_set/window
553win_wch/window
554win_wchnstr/window
555win_wchstr/window
556winch/window
557winchnstr/window
558winchstr/window
559winnstr/window
560winnwstr/window
561wins_nwstr/window
562wins_wch/window
563wins_wstr/window
564winsch/window
565winsdelln/window
566winsertln/window
567winsnstr/window
568winsstr/window
569winstr/window
570winwstr/window
571wmouse_trafo/window
572wmove/window
573wnoutrefresh/screen
574wprintw/window
575wredrawln/window
576wrefresh/screen
577wresize/window locks(windowlist)
578wscanw/screen
579wscrl/window
580wsetscrreg/window
581wstandend/window
582wstandout/window
583wsyncdown/screen (affects window plus parents)
584wsyncup/screen (affects window plus parents)
585wtimeout/window
586wtouchln/window
587wunctrl/global (static data)
588wvline/window
589wvline_set/window
590.TE
591.\" ***************************************************************************
592.SH RETURN VALUE
593These functions all return \fBTRUE\fP or \fBFALSE\fP, except as noted.
594.SH NOTES
595Both a macro and a function are provided for each name.
596.SH PORTABILITY
597These routines are specific to ncurses.
598They were not supported on Version 7, BSD or System V implementations.
599It is recommended that any code depending on ncurses extensions
600be conditioned using NCURSES_VERSION.
601.SH SEE ALSO
602\fBcurses\fP(3),
603\fBcurs_opaque\fP(3),
604\fBcurs_variables\fP(3).