aboutsummaryrefslogtreecommitdiff
path: root/man/curs_threads.3x
blob: 17dabdb7b40a560971884e8bc1c45c7c6301d498 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
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: