5b8e708d099a3ab48a88a295d8aec4afb942b7f3
[ncurses.git] / man / ncurses.3x
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
4 .\" Copyright 1998-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: ncurses.3x,v 1.149 2020/10/03 20:15:52 tom Exp $
32 .hy 0
33 .TH ncurses 3X ""
34 .ie \n(.g .ds `` \(lq
35 .el       .ds `` ``
36 .ie \n(.g .ds '' \(rq
37 .el       .ds '' ''
38 .de bP
39 .ie n  .IP \(bu 4
40 .el    .IP \(bu 2
41 ..
42 .de NS
43 .ie n  .sp
44 .el    .sp .5
45 .ie n  .in +4
46 .el    .in +2
47 .nf
48 .ft C                   \" Courier
49 ..
50 .de NE
51 .fi
52 .ft R
53 .ie n  .in -4
54 .el    .in -2
55 ..
56 .ds n 5
57 .ds d @TERMINFO@
58 .SH NAME
59 \fBncurses\fR \- CRT screen handling and optimization package
60 .SH SYNOPSIS
61 \fB#include <curses.h>\fR
62 .br
63 .SH DESCRIPTION
64 The \fBncurses\fR library routines give the user a terminal-independent method
65 of updating character screens with reasonable optimization.
66 This implementation is \*(``new curses\*('' (ncurses) and
67 is the approved replacement for
68 4.4BSD classic curses, which has been discontinued.
69 This describes \fBncurses\fR
70 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
71 .PP
72 The \fBncurses\fR library emulates the curses library of
73 System V Release 4 UNIX,
74 and XPG4 (X/Open Portability Guide) curses (also known as XSI curses).
75 XSI stands for X/Open System Interfaces Extension.
76 The \fBncurses\fR library is freely redistributable in source form.
77 Differences from the SVr4
78 curses are summarized under the
79 \fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
80 described in detail in the respective
81 \fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
82 of individual man pages.
83 .PP
84 The \fBncurses\fR library also provides many useful extensions,
85 i.e., features which cannot be implemented by a simple add-on library
86 but which require access to the internals of the library.
87 .PP
88 A program using these routines must be linked with the \fB\-lncurses\fR option,
89 or (if it has been generated) with the debugging library \fB\-lncurses_g\fR.
90 (Your system integrator may also have installed these libraries under
91 the names \fB\-lcurses\fR and \fB\-lcurses_g\fR.)
92 The ncurses_g library generates trace logs (in a file called 'trace' in the
93 current directory) that describe curses actions.
94 See also the section on \fBALTERNATE CONFIGURATIONS\fP.
95 .PP
96 The \fBncurses\fR package supports: overall screen, window and pad
97 manipulation; output to windows and pads; reading terminal input; control over
98 terminal and \fBcurses\fR input and output options; environment query
99 routines; color manipulation; use of soft label keys; terminfo capabilities;
100 and access to low-level terminal-manipulation routines.
101 .SS Initialization
102 .PP
103 The library uses the locale which the calling program has initialized.
104 That is normally done with \fBsetlocale\fP:
105 .NS
106 \fBsetlocale(LC_ALL, "");\fP
107 .NE
108 .PP
109 If the locale is not initialized,
110 the library assumes that characters are printable as in ISO\-8859\-1,
111 to work with certain legacy programs.
112 You should initialize the locale and not rely on specific details of
113 the library when the locale has not been setup.
114 .PP
115 The function \fBinitscr\fR or \fBnewterm\fR
116 must be called to initialize the library
117 before any of the other routines that deal with windows
118 and screens are used.
119 The routine \fBendwin\fR(3X) must be called before exiting.
120 .PP
121 To get character-at-a-time input without echoing (most
122 interactive, screen oriented programs want this), the following
123 sequence should be used:
124 .NS
125 \fBinitscr(); cbreak(); noecho();\fR
126 .NE
127 .PP
128 Most programs would additionally use the sequence:
129 .NS
130 \fBintrflush(stdscr, FALSE);\fR
131 \fBkeypad(stdscr, TRUE);\fR
132 .NE
133 .PP
134 Before a \fBcurses\fR program is run, the tab stops of the terminal
135 should be set and its initialization strings, if defined, must be output.
136 This can be done by executing the \fB@TPUT@ init\fR command
137 after the shell environment variable \fBTERM\fR has been exported.
138 \fB@TSET@(1)\fR is usually responsible for doing this.
139 [See \fBterminfo\fR(\*n) for further details.]
140 .SS Datatypes
141 .PP
142 The \fBncurses\fR library permits manipulation of data structures,
143 called \fIwindows\fR, which can be thought of as two-dimensional
144 arrays of characters representing all or part of a CRT screen.
145 A default window called \fBstdscr\fR, which is the size of the terminal
146 screen, is supplied.
147 Others may be created with \fBnewwin\fR.
148 .PP
149 Note that \fBcurses\fR does not handle overlapping windows, that's done by
150 the \fBpanel\fR(3X) library.
151 This means that you can either use
152 \fBstdscr\fR or divide the screen into tiled windows and not using
153 \fBstdscr\fR at all.
154 Mixing the two will result in unpredictable, and undesired, effects.
155 .PP
156 Windows are referred to by variables declared as \fBWINDOW *\fR.
157 These data structures are manipulated with routines described here and
158 elsewhere in the \fBncurses\fR manual pages.
159 Among those, the most basic
160 routines are \fBmove\fR and \fBaddch\fR.
161 More general versions of
162 these routines are included with names beginning with \fBw\fR,
163 allowing the user to specify a window.
164 The routines not beginning
165 with \fBw\fR affect \fBstdscr\fR.
166 .PP
167 After using routines to manipulate a window, \fBrefresh\fR(3X) is called,
168 telling \fBcurses\fR to make the user's CRT screen look like
169 \fBstdscr\fR.
170 The characters in a window are actually of type
171 \fBchtype\fR, (character and attribute data) so that other information
172 about the character may also be stored with each character.
173 .PP
174 Special windows called \fIpads\fR may also be manipulated.
175 These are windows
176 which are not constrained to the size of the screen and whose contents need not
177 be completely displayed.
178 See \fBcurs_pad\fR(3X) for more information.
179 .PP
180 In addition to drawing characters on the screen, video attributes and colors
181 may be supported, causing the characters to show up in such modes as
182 underlined, in reverse video, or in color on terminals that support such
183 display enhancements.
184 Line drawing characters may be specified to be output.
185 On input, \fBcurses\fR is also able to translate arrow and function keys that
186 transmit escape sequences into single values.
187 The video attributes, line
188 drawing characters, and input values use names, defined in \fB<curses.h>\fR,
189 such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
190 .SS Environment variables
191 .PP
192 If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
193 program is executing in a window environment, line and column information in
194 the environment will override information read by \fIterminfo\fR.
195 This would affect a program running in an AT&T 630 layer,
196 for example, where the size of a
197 screen is changeable (see \fBENVIRONMENT\fR).
198 .PP
199 If the environment variable \fBTERMINFO\fR is defined, any program using
200 \fBcurses\fR checks for a local terminal definition before checking in the
201 standard place.
202 For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
203 compiled terminal definition is found in
204 .NS
205 \fB\*d/a/att4424\fR.
206 .NE
207 .PP
208 (The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
209 creation of huge directories.)  However, if \fBTERMINFO\fR is set to
210 \fB$HOME/myterms\fR, \fBcurses\fR first checks
211 .NS
212 \fB$HOME/myterms/a/att4424\fR,
213 .NE
214 .PP
215 and if that fails, it then checks
216 .NS
217 \fB\*d/a/att4424\fR.
218 .NE
219 .PP
220 This is useful for developing experimental definitions or when write
221 permission in \fB\*d\fR is not available.
222 .PP
223 The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
224 \fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
225 screen.
226 The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
227 \fB0\fR, respectively.
228 .PP
229 The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
230 which is used for certain low-level operations like clearing and redrawing a
231 screen containing garbage.
232 The \fBcurscr\fR can be used in only a few routines.
233 .\"
234 .SS Routine and Argument Names
235 Many \fBcurses\fR routines have two or more versions.
236 The routines prefixed with \fBw\fR require a window argument.
237 The routines prefixed with \fBp\fR require a pad argument.
238 Those without a prefix generally use \fBstdscr\fR.
239 .PP
240 The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
241 coordinate to move to before performing the appropriate action.
242 The \fBmv\fR routines imply a call to \fBmove\fR before the call to the
243 other routine.
244 The coordinate \fIy\fR always refers to the row (of
245 the window), and \fIx\fR always refers to the column.
246 The upper left-hand corner is always (0,0), not (1,1).
247 .PP
248 The routines prefixed with \fBmvw\fR take both a window argument and
249 \fIx\fR and \fIy\fR coordinates.
250 The window argument is always specified before the coordinates.
251 .PP
252 In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
253 pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
254 \fBWINDOW\fR.
255 .PP
256 Option setting routines require a Boolean flag \fIbf\fR with the value
257 \fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.
258 Most of the data types used in the library routines,
259 such as \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and \fBchtype\fR
260 are defined in \fB<curses.h>\fR.
261 Types used for the terminfo routines such as
262 \fBTERMINAL\fR are defined in \fB<term.h>\fR.
263 .PP
264 This manual page describes functions which may appear in any configuration
265 of the library.
266 There are two common configurations of the library:
267 .RS 3
268 .TP 5
269 .I ncurses
270 the \*(``normal\*('' library, which handles 8-bit characters.
271 The normal (8-bit) library stores characters combined with attributes
272 in \fBchtype\fP data.
273 .IP
274 Attributes alone (no corresponding character) may be stored in \fBchtype\fP
275 or the equivalent \fBattr_t\fP data.
276 In either case, the data is stored in something like an integer.
277 .IP
278 Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP.
279 .TP 5
280 .I ncursesw
281 the so-called \*(``wide\*('' library, which handles multibyte characters
282 (see the section on \fBALTERNATE CONFIGURATIONS\fP).
283 The \*(``wide\*('' library includes all of the calls
284 from the \*(``normal\*('' library.
285 It adds about one third more calls using data types which store
286 multibyte characters:
287 .RS 5
288 .TP 5
289 .B cchar_t
290 corresponds to \fBchtype\fP.
291 However it is a structure, because more data is stored than can fit into
292 an integer.
293 The characters are large enough to require a full integer value \- and there
294 may be more than one character per cell.
295 The video attributes and color are stored in separate fields of the structure.
296 .IP
297 Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBcchar_t\fP.
298 .IP
299 The \fBsetcchar\fP(3X) and \fBgetcchar\fP(3X)
300 functions store and retrieve the data from
301 a \fBcchar_t\fP structure.
302 .TP 5
303 .B wchar_t
304 stores a \*(``wide\*('' character.
305 Like \fBchtype\fP, this may be an integer.
306 .TP 5
307 .B wint_t
308 stores a \fBwchar_t\fP or \fBWEOF\fP \- not the same, though both may have
309 the same size.
310 .RE
311 .IP
312 The \*(``wide\*('' library provides new functions which are analogous to
313 functions in the \*(``normal\*('' library.
314 There is a naming convention which relates many of the normal/wide variants:
315 a \*(``_w\*('' is inserted into the name.
316 For example, \fBwaddch\fP becomes \fBwadd_wch\fP.
317 .RE
318 .PP
319 .\"
320 .SS Routine Name Index
321 The following table lists the \fBcurses\fR routines provided in
322 the \*(``normal\*('' and \*(``wide\*('' libraries and the names of
323 the manual pages on which they are described.
324 Routines flagged with \*(``*\*(''
325 are ncurses-specific, not described by XPG4 or present in SVr4.
326 .PP
327 .TS
328 center tab(/);
329 l l
330 l l .
331 \fBcurses\fR Routine Name/Manual Page Name
332 =
333 COLOR_PAIR/\fBcurs_color\fR(3X)
334 PAIR_NUMBER/\fBcurs_attr\fR(3X)
335 add_wch/\fBcurs_add_wch\fR(3X)
336 add_wchnstr/\fBcurs_add_wchstr\fR(3X)
337 add_wchstr/\fBcurs_add_wchstr\fR(3X)
338 addch/\fBcurs_addch\fR(3X)
339 addchnstr/\fBcurs_addchstr\fR(3X)
340 addchstr/\fBcurs_addchstr\fR(3X)
341 addnstr/\fBcurs_addstr\fR(3X)
342 addnwstr/\fBcurs_addwstr\fR(3X)
343 addstr/\fBcurs_addstr\fR(3X)
344 addwstr/\fBcurs_addwstr\fR(3X)
345 alloc_pair/\fBnew_pair\fR(3X)*
346 assume_default_colors/\fBdefault_colors\fR(3X)*
347 attr_get/\fBcurs_attr\fR(3X)
348 attr_off/\fBcurs_attr\fR(3X)
349 attr_on/\fBcurs_attr\fR(3X)
350 attr_set/\fBcurs_attr\fR(3X)
351 attroff/\fBcurs_attr\fR(3X)
352 attron/\fBcurs_attr\fR(3X)
353 attrset/\fBcurs_attr\fR(3X)
354 baudrate/\fBcurs_termattrs\fR(3X)
355 beep/\fBcurs_beep\fR(3X)
356 bkgd/\fBcurs_bkgd\fR(3X)
357 bkgdset/\fBcurs_bkgd\fR(3X)
358 bkgrnd/\fBcurs_bkgrnd\fR(3X)
359 bkgrndset/\fBcurs_bkgrnd\fR(3X)
360 border/\fBcurs_border\fR(3X)
361 border_set/\fBcurs_border_set\fR(3X)
362 box/\fBcurs_border\fR(3X)
363 box_set/\fBcurs_border_set\fR(3X)
364 can_change_color/\fBcurs_color\fR(3X)
365 cbreak/\fBcurs_inopts\fR(3X)
366 chgat/\fBcurs_attr\fR(3X)
367 clear/\fBcurs_clear\fR(3X)
368 clearok/\fBcurs_outopts\fR(3X)
369 clrtobot/\fBcurs_clear\fR(3X)
370 clrtoeol/\fBcurs_clear\fR(3X)
371 color_content/\fBcurs_color\fR(3X)
372 color_set/\fBcurs_attr\fR(3X)
373 copywin/\fBcurs_overlay\fR(3X)
374 curs_set/\fBcurs_kernel\fR(3X)
375 curses_trace/\fBcurs_trace\fR(3X)*
376 curses_version/\fBcurs_extend\fR(3X)*
377 def_prog_mode/\fBcurs_kernel\fR(3X)
378 def_shell_mode/\fBcurs_kernel\fR(3X)
379 define_key/\fBdefine_key\fR(3X)*
380 del_curterm/\fBcurs_terminfo\fR(3X)
381 delay_output/\fBcurs_util\fR(3X)
382 delch/\fBcurs_delch\fR(3X)
383 deleteln/\fBcurs_deleteln\fR(3X)
384 delscreen/\fBcurs_initscr\fR(3X)
385 delwin/\fBcurs_window\fR(3X)
386 derwin/\fBcurs_window\fR(3X)
387 doupdate/\fBcurs_refresh\fR(3X)
388 dupwin/\fBcurs_window\fR(3X)
389 echo/\fBcurs_inopts\fR(3X)
390 echo_wchar/\fBcurs_add_wch\fR(3X)
391 echochar/\fBcurs_addch\fR(3X)
392 endwin/\fBcurs_initscr\fR(3X)
393 erase/\fBcurs_clear\fR(3X)
394 erasechar/\fBcurs_termattrs\fR(3X)
395 erasewchar/\fBcurs_termattrs\fR(3X)
396 exit_curses/\fBcurs_memleaks\fR(3X)*
397 exit_terminfo/\fBcurs_memleaks\fR(3X)*
398 extended_color_content/\fBcurs_color\fR(3X)*
399 extended_pair_content/\fBcurs_color\fR(3X)*
400 extended_slk_color/\fBcurs_slk\fR(3X)*
401 filter/\fBcurs_util\fR(3X)
402 find_pair/\fBnew_pair\fR(3X)*
403 flash/\fBcurs_beep\fR(3X)
404 flushinp/\fBcurs_util\fR(3X)
405 free_pair/\fBnew_pair\fR(3X)*
406 get_wch/\fBcurs_get_wch\fR(3X)
407 get_wstr/\fBcurs_get_wstr\fR(3X)
408 getattrs/\fBcurs_attr\fR(3X)
409 getbegx/\fBcurs_legacy\fR(3X)*
410 getbegy/\fBcurs_legacy\fR(3X)*
411 getbegyx/\fBcurs_getyx\fR(3X)
412 getbkgd/\fBcurs_bkgd\fR(3X)
413 getbkgrnd/\fBcurs_bkgrnd\fR(3X)
414 getcchar/\fBcurs_getcchar\fR(3X)
415 getch/\fBcurs_getch\fR(3X)
416 getcurx/\fBcurs_legacy\fR(3X)*
417 getcury/\fBcurs_legacy\fR(3X)*
418 getmaxx/\fBcurs_legacy\fR(3X)*
419 getmaxy/\fBcurs_legacy\fR(3X)*
420 getmaxyx/\fBcurs_getyx\fR(3X)
421 getmouse/\fBcurs_mouse\fR(3X)*
422 getn_wstr/\fBcurs_get_wstr\fR(3X)
423 getnstr/\fBcurs_getstr\fR(3X)
424 getparx/\fBcurs_legacy\fR(3X)*
425 getpary/\fBcurs_legacy\fR(3X)*
426 getparyx/\fBcurs_getyx\fR(3X)
427 getstr/\fBcurs_getstr\fR(3X)
428 getsyx/\fBcurs_kernel\fR(3X)
429 getwin/\fBcurs_util\fR(3X)
430 getyx/\fBcurs_getyx\fR(3X)
431 halfdelay/\fBcurs_inopts\fR(3X)
432 has_colors/\fBcurs_color\fR(3X)
433 has_ic/\fBcurs_termattrs\fR(3X)
434 has_il/\fBcurs_termattrs\fR(3X)
435 has_key/\fBcurs_getch\fR(3X)*
436 has_mouse/\fBcurs_mouse\fR(3X)*
437 hline/\fBcurs_border\fR(3X)
438 hline_set/\fBcurs_border_set\fR(3X)
439 idcok/\fBcurs_outopts\fR(3X)
440 idlok/\fBcurs_outopts\fR(3X)
441 immedok/\fBcurs_outopts\fR(3X)
442 in_wch/\fBcurs_in_wch\fR(3X)
443 in_wchnstr/\fBcurs_in_wchstr\fR(3X)
444 in_wchstr/\fBcurs_in_wchstr\fR(3X)
445 inch/\fBcurs_inch\fR(3X)
446 inchnstr/\fBcurs_inchstr\fR(3X)
447 inchstr/\fBcurs_inchstr\fR(3X)
448 init_color/\fBcurs_color\fR(3X)
449 init_extended_color/\fBcurs_color\fR(3X)*
450 init_extended_pair/\fBcurs_color\fR(3X)*
451 init_pair/\fBcurs_color\fR(3X)
452 initscr/\fBcurs_initscr\fR(3X)
453 innstr/\fBcurs_instr\fR(3X)
454 innwstr/\fBcurs_inwstr\fR(3X)
455 ins_nwstr/\fBcurs_ins_wstr\fR(3X)
456 ins_wch/\fBcurs_ins_wch\fR(3X)
457 ins_wstr/\fBcurs_ins_wstr\fR(3X)
458 insch/\fBcurs_insch\fR(3X)
459 insdelln/\fBcurs_deleteln\fR(3X)
460 insertln/\fBcurs_deleteln\fR(3X)
461 insnstr/\fBcurs_insstr\fR(3X)
462 insstr/\fBcurs_insstr\fR(3X)
463 instr/\fBcurs_instr\fR(3X)
464 intrflush/\fBcurs_inopts\fR(3X)
465 inwstr/\fBcurs_inwstr\fR(3X)
466 is_cleared/\fBcurs_opaque\fR(3X)*
467 is_idcok/\fBcurs_opaque\fR(3X)*
468 is_idlok/\fBcurs_opaque\fR(3X)*
469 is_immedok/\fBcurs_opaque\fR(3X)*
470 is_keypad/\fBcurs_opaque\fR(3X)*
471 is_leaveok/\fBcurs_opaque\fR(3X)*
472 is_linetouched/\fBcurs_touch\fR(3X)
473 is_nodelay/\fBcurs_opaque\fR(3X)*
474 is_notimeout/\fBcurs_opaque\fR(3X)*
475 is_pad/\fBcurs_opaque\fR(3X)*
476 is_scrollok/\fBcurs_opaque\fR(3X)*
477 is_subwin/\fBcurs_opaque\fR(3X)*
478 is_syncok/\fBcurs_opaque\fR(3X)*
479 is_term_resized/\fBresizeterm\fR(3X)*
480 is_wintouched/\fBcurs_touch\fR(3X)
481 isendwin/\fBcurs_initscr\fR(3X)
482 key_defined/\fBkey_defined\fR(3X)*
483 key_name/\fBcurs_util\fR(3X)
484 keybound/\fBkeybound\fR(3X)*
485 keyname/\fBcurs_util\fR(3X)
486 keyok/\fBkeyok\fR(3X)*
487 keypad/\fBcurs_inopts\fR(3X)
488 killchar/\fBcurs_termattrs\fR(3X)
489 killwchar/\fBcurs_termattrs\fR(3X)
490 leaveok/\fBcurs_outopts\fR(3X)
491 longname/\fBcurs_termattrs\fR(3X)
492 mcprint/\fBcurs_print\fR(3X)*
493 meta/\fBcurs_inopts\fR(3X)
494 mouse_trafo/\fBcurs_mouse\fR(3X)*
495 mouseinterval/\fBcurs_mouse\fR(3X)*
496 mousemask/\fBcurs_mouse\fR(3X)*
497 move/\fBcurs_move\fR(3X)
498 mvadd_wch/\fBcurs_add_wch\fR(3X)
499 mvadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
500 mvadd_wchstr/\fBcurs_add_wchstr\fR(3X)
501 mvaddch/\fBcurs_addch\fR(3X)
502 mvaddchnstr/\fBcurs_addchstr\fR(3X)
503 mvaddchstr/\fBcurs_addchstr\fR(3X)
504 mvaddnstr/\fBcurs_addstr\fR(3X)
505 mvaddnwstr/\fBcurs_addwstr\fR(3X)
506 mvaddstr/\fBcurs_addstr\fR(3X)
507 mvaddwstr/\fBcurs_addwstr\fR(3X)
508 mvchgat/\fBcurs_attr\fR(3X)
509 mvcur/\fBcurs_terminfo\fR(3X)
510 mvdelch/\fBcurs_delch\fR(3X)
511 mvderwin/\fBcurs_window\fR(3X)
512 mvget_wch/\fBcurs_get_wch\fR(3X)
513 mvget_wstr/\fBcurs_get_wstr\fR(3X)
514 mvgetch/\fBcurs_getch\fR(3X)
515 mvgetn_wstr/\fBcurs_get_wstr\fR(3X)
516 mvgetnstr/\fBcurs_getstr\fR(3X)
517 mvgetstr/\fBcurs_getstr\fR(3X)
518 mvhline/\fBcurs_border\fR(3X)
519 mvhline_set/\fBcurs_border_set\fR(3X)
520 mvin_wch/\fBcurs_in_wch\fR(3X)
521 mvin_wchnstr/\fBcurs_in_wchstr\fR(3X)
522 mvin_wchstr/\fBcurs_in_wchstr\fR(3X)
523 mvinch/\fBcurs_inch\fR(3X)
524 mvinchnstr/\fBcurs_inchstr\fR(3X)
525 mvinchstr/\fBcurs_inchstr\fR(3X)
526 mvinnstr/\fBcurs_instr\fR(3X)
527 mvinnwstr/\fBcurs_inwstr\fR(3X)
528 mvins_nwstr/\fBcurs_ins_wstr\fR(3X)
529 mvins_wch/\fBcurs_ins_wch\fR(3X)
530 mvins_wstr/\fBcurs_ins_wstr\fR(3X)
531 mvinsch/\fBcurs_insch\fR(3X)
532 mvinsnstr/\fBcurs_insstr\fR(3X)
533 mvinsstr/\fBcurs_insstr\fR(3X)
534 mvinstr/\fBcurs_instr\fR(3X)
535 mvinwstr/\fBcurs_inwstr\fR(3X)
536 mvprintw/\fBcurs_printw\fR(3X)
537 mvscanw/\fBcurs_scanw\fR(3X)
538 mvvline/\fBcurs_border\fR(3X)
539 mvvline_set/\fBcurs_border_set\fR(3X)
540 mvwadd_wch/\fBcurs_add_wch\fR(3X)
541 mvwadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
542 mvwadd_wchstr/\fBcurs_add_wchstr\fR(3X)
543 mvwaddch/\fBcurs_addch\fR(3X)
544 mvwaddchnstr/\fBcurs_addchstr\fR(3X)
545 mvwaddchstr/\fBcurs_addchstr\fR(3X)
546 mvwaddnstr/\fBcurs_addstr\fR(3X)
547 mvwaddnwstr/\fBcurs_addwstr\fR(3X)
548 mvwaddstr/\fBcurs_addstr\fR(3X)
549 mvwaddwstr/\fBcurs_addwstr\fR(3X)
550 mvwchgat/\fBcurs_attr\fR(3X)
551 mvwdelch/\fBcurs_delch\fR(3X)
552 mvwget_wch/\fBcurs_get_wch\fR(3X)
553 mvwget_wstr/\fBcurs_get_wstr\fR(3X)
554 mvwgetch/\fBcurs_getch\fR(3X)
555 mvwgetn_wstr/\fBcurs_get_wstr\fR(3X)
556 mvwgetnstr/\fBcurs_getstr\fR(3X)
557 mvwgetstr/\fBcurs_getstr\fR(3X)
558 mvwhline/\fBcurs_border\fR(3X)
559 mvwhline_set/\fBcurs_border_set\fR(3X)
560 mvwin/\fBcurs_window\fR(3X)
561 mvwin_wch/\fBcurs_in_wch\fR(3X)
562 mvwin_wchnstr/\fBcurs_in_wchstr\fR(3X)
563 mvwin_wchstr/\fBcurs_in_wchstr\fR(3X)
564 mvwinch/\fBcurs_inch\fR(3X)
565 mvwinchnstr/\fBcurs_inchstr\fR(3X)
566 mvwinchstr/\fBcurs_inchstr\fR(3X)
567 mvwinnstr/\fBcurs_instr\fR(3X)
568 mvwinnwstr/\fBcurs_inwstr\fR(3X)
569 mvwins_nwstr/\fBcurs_ins_wstr\fR(3X)
570 mvwins_wch/\fBcurs_ins_wch\fR(3X)
571 mvwins_wstr/\fBcurs_ins_wstr\fR(3X)
572 mvwinsch/\fBcurs_insch\fR(3X)
573 mvwinsnstr/\fBcurs_insstr\fR(3X)
574 mvwinsstr/\fBcurs_insstr\fR(3X)
575 mvwinstr/\fBcurs_instr\fR(3X)
576 mvwinwstr/\fBcurs_inwstr\fR(3X)
577 mvwprintw/\fBcurs_printw\fR(3X)
578 mvwscanw/\fBcurs_scanw\fR(3X)
579 mvwvline/\fBcurs_border\fR(3X)
580 mvwvline_set/\fBcurs_border_set\fR(3X)
581 napms/\fBcurs_kernel\fR(3X)
582 newpad/\fBcurs_pad\fR(3X)
583 newterm/\fBcurs_initscr\fR(3X)
584 newwin/\fBcurs_window\fR(3X)
585 nl/\fBcurs_outopts\fR(3X)
586 nocbreak/\fBcurs_inopts\fR(3X)
587 nodelay/\fBcurs_inopts\fR(3X)
588 noecho/\fBcurs_inopts\fR(3X)
589 nofilter/\fBcurs_util\fR(3X)*
590 nonl/\fBcurs_inopts\fR(3X)
591 noqiflush/\fBcurs_inopts\fR(3X)
592 noraw/\fBcurs_inopts\fR(3X)
593 notimeout/\fBcurs_inopts\fR(3X)
594 overlay/\fBcurs_overlay\fR(3X)
595 overwrite/\fBcurs_overlay\fR(3X)
596 pair_content/\fBcurs_color\fR(3X)
597 pecho_wchar/\fBcurs_pad\fR(3X)*
598 pechochar/\fBcurs_pad\fR(3X)
599 pnoutrefresh/\fBcurs_pad\fR(3X)
600 prefresh/\fBcurs_pad\fR(3X)
601 printw/\fBcurs_printw\fR(3X)
602 putp/\fBcurs_terminfo\fR(3X)
603 putwin/\fBcurs_util\fR(3X)
604 qiflush/\fBcurs_inopts\fR(3X)
605 raw/\fBcurs_inopts\fR(3X)
606 redrawwin/\fBcurs_refresh\fR(3X)
607 refresh/\fBcurs_refresh\fR(3X)
608 reset_color_pairs/\fBcurs_color\fR(3X)*
609 reset_prog_mode/\fBcurs_kernel\fR(3X)
610 reset_shell_mode/\fBcurs_kernel\fR(3X)
611 resetty/\fBcurs_kernel\fR(3X)
612 resize_term/\fBresizeterm\fR(3X)*
613 resizeterm/\fBresizeterm\fR(3X)*
614 restartterm/\fBcurs_terminfo\fR(3X)
615 ripoffline/\fBcurs_kernel\fR(3X)
616 savetty/\fBcurs_kernel\fR(3X)
617 scanw/\fBcurs_scanw\fR(3X)
618 scr_dump/\fBcurs_scr_dump\fR(3X)
619 scr_init/\fBcurs_scr_dump\fR(3X)
620 scr_restore/\fBcurs_scr_dump\fR(3X)
621 scr_set/\fBcurs_scr_dump\fR(3X)
622 scrl/\fBcurs_scroll\fR(3X)
623 scroll/\fBcurs_scroll\fR(3X)
624 scrollok/\fBcurs_outopts\fR(3X)
625 set_curterm/\fBcurs_terminfo\fR(3X)
626 set_term/\fBcurs_initscr\fR(3X)
627 setcchar/\fBcurs_getcchar\fR(3X)
628 setscrreg/\fBcurs_outopts\fR(3X)
629 setsyx/\fBcurs_kernel\fR(3X)
630 setterm/\fBcurs_terminfo\fR(3X)
631 setupterm/\fBcurs_terminfo\fR(3X)
632 slk_attr/\fBcurs_slk\fR(3X)*
633 slk_attr_off/\fBcurs_slk\fR(3X)
634 slk_attr_on/\fBcurs_slk\fR(3X)
635 slk_attr_set/\fBcurs_slk\fR(3X)
636 slk_attroff/\fBcurs_slk\fR(3X)
637 slk_attron/\fBcurs_slk\fR(3X)
638 slk_attrset/\fBcurs_slk\fR(3X)
639 slk_clear/\fBcurs_slk\fR(3X)
640 slk_color/\fBcurs_slk\fR(3X)
641 slk_init/\fBcurs_slk\fR(3X)
642 slk_label/\fBcurs_slk\fR(3X)
643 slk_noutrefresh/\fBcurs_slk\fR(3X)
644 slk_refresh/\fBcurs_slk\fR(3X)
645 slk_restore/\fBcurs_slk\fR(3X)
646 slk_set/\fBcurs_slk\fR(3X)
647 slk_touch/\fBcurs_slk\fR(3X)
648 slk_wset/\fBcurs_slk\fR(3X)*
649 standend/\fBcurs_attr\fR(3X)
650 standout/\fBcurs_attr\fR(3X)
651 start_color/\fBcurs_color\fR(3X)
652 subpad/\fBcurs_pad\fR(3X)
653 subwin/\fBcurs_window\fR(3X)
654 syncok/\fBcurs_window\fR(3X)
655 term_attrs/\fBcurs_termattrs\fR(3X)
656 termattrs/\fBcurs_termattrs\fR(3X)
657 termname/\fBcurs_termattrs\fR(3X)
658 tgetent/\fBcurs_termcap\fR(3X)
659 tgetflag/\fBcurs_termcap\fR(3X)
660 tgetnum/\fBcurs_termcap\fR(3X)
661 tgetstr/\fBcurs_termcap\fR(3X)
662 tgoto/\fBcurs_termcap\fR(3X)
663 tigetflag/\fBcurs_terminfo\fR(3X)
664 tigetnum/\fBcurs_terminfo\fR(3X)
665 tigetstr/\fBcurs_terminfo\fR(3X)
666 timeout/\fBcurs_inopts\fR(3X)
667 tiparm/\fBcurs_terminfo\fR(3X)*
668 touchline/\fBcurs_touch\fR(3X)
669 touchwin/\fBcurs_touch\fR(3X)
670 tparm/\fBcurs_terminfo\fR(3X)
671 tputs/\fBcurs_termcap\fR(3X)
672 tputs/\fBcurs_terminfo\fR(3X)
673 trace/\fBcurs_trace\fR(3X)*
674 typeahead/\fBcurs_inopts\fR(3X)
675 unctrl/\fBcurs_util\fR(3X)
676 unget_wch/\fBcurs_get_wch\fR(3X)
677 ungetch/\fBcurs_getch\fR(3X)
678 ungetmouse/\fBcurs_mouse\fR(3X)*
679 untouchwin/\fBcurs_touch\fR(3X)
680 use_default_colors/\fBdefault_colors\fR(3X)*
681 use_env/\fBcurs_util\fR(3X)
682 use_extended_names/\fBcurs_extend\fR(3X)*
683 use_legacy_coding/\fBlegacy_coding\fR(3X)*
684 use_tioctl/\fBcurs_util\fR(3X)*
685 vid_attr/\fBcurs_terminfo\fR(3X)
686 vid_puts/\fBcurs_terminfo\fR(3X)
687 vidattr/\fBcurs_terminfo\fR(3X)
688 vidputs/\fBcurs_terminfo\fR(3X)
689 vline/\fBcurs_border\fR(3X)
690 vline_set/\fBcurs_border_set\fR(3X)
691 vw_printw/\fBcurs_printw\fR(3X)
692 vw_scanw/\fBcurs_scanw\fR(3X)
693 vwprintw/\fBcurs_printw\fR(3X)
694 vwscanw/\fBcurs_scanw\fR(3X)
695 wadd_wch/\fBcurs_add_wch\fR(3X)
696 wadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
697 wadd_wchstr/\fBcurs_add_wchstr\fR(3X)
698 waddch/\fBcurs_addch\fR(3X)
699 waddchnstr/\fBcurs_addchstr\fR(3X)
700 waddchstr/\fBcurs_addchstr\fR(3X)
701 waddnstr/\fBcurs_addstr\fR(3X)
702 waddnwstr/\fBcurs_addwstr\fR(3X)
703 waddstr/\fBcurs_addstr\fR(3X)
704 waddwstr/\fBcurs_addwstr\fR(3X)
705 wattr_get/\fBcurs_attr\fR(3X)
706 wattr_off/\fBcurs_attr\fR(3X)
707 wattr_on/\fBcurs_attr\fR(3X)
708 wattr_set/\fBcurs_attr\fR(3X)
709 wattroff/\fBcurs_attr\fR(3X)
710 wattron/\fBcurs_attr\fR(3X)
711 wattrset/\fBcurs_attr\fR(3X)
712 wbkgd/\fBcurs_bkgd\fR(3X)
713 wbkgdset/\fBcurs_bkgd\fR(3X)
714 wbkgrnd/\fBcurs_bkgrnd\fR(3X)
715 wbkgrndset/\fBcurs_bkgrnd\fR(3X)
716 wborder/\fBcurs_border\fR(3X)
717 wborder_set/\fBcurs_border_set\fR(3X)
718 wchgat/\fBcurs_attr\fR(3X)
719 wclear/\fBcurs_clear\fR(3X)
720 wclrtobot/\fBcurs_clear\fR(3X)
721 wclrtoeol/\fBcurs_clear\fR(3X)
722 wcolor_set/\fBcurs_attr\fR(3X)
723 wcursyncup/\fBcurs_window\fR(3X)
724 wdelch/\fBcurs_delch\fR(3X)
725 wdeleteln/\fBcurs_deleteln\fR(3X)
726 wecho_wchar/\fBcurs_add_wch\fR(3X)
727 wechochar/\fBcurs_addch\fR(3X)
728 wenclose/\fBcurs_mouse\fR(3X)*
729 werase/\fBcurs_clear\fR(3X)
730 wget_wch/\fBcurs_get_wch\fR(3X)
731 wget_wstr/\fBcurs_get_wstr\fR(3X)
732 wgetbkgrnd/\fBcurs_bkgrnd\fR(3X)
733 wgetch/\fBcurs_getch\fR(3X)
734 wgetdelay/\fBcurs_opaque\fR(3X)*
735 wgetn_wstr/\fBcurs_get_wstr\fR(3X)
736 wgetnstr/\fBcurs_getstr\fR(3X)
737 wgetparent/\fBcurs_opaque\fR(3X)*
738 wgetscrreg/\fBcurs_opaque\fR(3X)*
739 wgetstr/\fBcurs_getstr\fR(3X)
740 whline/\fBcurs_border\fR(3X)
741 whline_set/\fBcurs_border_set\fR(3X)
742 win_wch/\fBcurs_in_wch\fR(3X)
743 win_wchnstr/\fBcurs_in_wchstr\fR(3X)
744 win_wchstr/\fBcurs_in_wchstr\fR(3X)
745 winch/\fBcurs_inch\fR(3X)
746 winchnstr/\fBcurs_inchstr\fR(3X)
747 winchstr/\fBcurs_inchstr\fR(3X)
748 winnstr/\fBcurs_instr\fR(3X)
749 winnwstr/\fBcurs_inwstr\fR(3X)
750 wins_nwstr/\fBcurs_ins_wstr\fR(3X)
751 wins_wch/\fBcurs_ins_wch\fR(3X)
752 wins_wstr/\fBcurs_ins_wstr\fR(3X)
753 winsch/\fBcurs_insch\fR(3X)
754 winsdelln/\fBcurs_deleteln\fR(3X)
755 winsertln/\fBcurs_deleteln\fR(3X)
756 winsnstr/\fBcurs_insstr\fR(3X)
757 winsstr/\fBcurs_insstr\fR(3X)
758 winstr/\fBcurs_instr\fR(3X)
759 winwstr/\fBcurs_inwstr\fR(3X)
760 wmouse_trafo/\fBcurs_mouse\fR(3X)*
761 wmove/\fBcurs_move\fR(3X)
762 wnoutrefresh/\fBcurs_refresh\fR(3X)
763 wprintw/\fBcurs_printw\fR(3X)
764 wredrawln/\fBcurs_refresh\fR(3X)
765 wrefresh/\fBcurs_refresh\fR(3X)
766 wresize/\fBwresize\fR(3X)*
767 wscanw/\fBcurs_scanw\fR(3X)
768 wscrl/\fBcurs_scroll\fR(3X)
769 wsetscrreg/\fBcurs_outopts\fR(3X)
770 wstandend/\fBcurs_attr\fR(3X)
771 wstandout/\fBcurs_attr\fR(3X)
772 wsyncdown/\fBcurs_window\fR(3X)
773 wsyncup/\fBcurs_window\fR(3X)
774 wtimeout/\fBcurs_inopts\fR(3X)
775 wtouchln/\fBcurs_touch\fR(3X)
776 wunctrl/\fBcurs_util\fR(3X)
777 wvline/\fBcurs_border\fR(3X)
778 wvline_set/\fBcurs_border_set\fR(3X)
779 .TE
780 .PP
781 Depending on the configuration,
782 additional sets of functions may be available:
783 .RS 3
784 .TP 5
785 \fBcurs_memleaks\fP(3X) - curses memory-leak checking
786 .TP 5
787 \fBcurs_sp_funcs\fP(3X) - curses screen-pointer extension
788 .TP 5
789 \fBcurs_threads\fP(3X) - curses thread support
790 .TP 5
791 \fBcurs_trace\fP(3X) - curses debugging routines
792 .RE
793 .SH RETURN VALUE
794 Routines that return an integer return \fBERR\fR upon failure and an
795 integer value other than \fBERR\fR upon successful completion, unless
796 otherwise noted in the routine descriptions.
797 .PP
798 As a general rule, routines check for null pointers passed as parameters,
799 and handle this as an error.
800 .PP
801 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
802 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.
803 The return values of
804 \fBsetscrreg\fR,
805 \fBwsetscrreg\fR,
806 \fBgetyx\fR,
807 \fBgetbegyx\fR, and
808 \fBgetmaxyx\fR are undefined (i.e., these should not be used as the
809 right-hand side of assignment statements).
810 .PP
811 Functions with a \*(``mv\*('' prefix first perform a cursor movement using
812 \fBwmove\fP, and return an error if the position is outside the window,
813 or if the window pointer is null.
814 Most \*(``mv\*(''-prefixed functions
815 (except variadic functions such as \fBmvprintw\fP)
816 are provided both as macros and functions.
817 .PP
818 Routines that return pointers return \fBNULL\fR on error.
819 .SH ENVIRONMENT
820 .PP
821 The following environment symbols are useful for customizing the
822 runtime behavior of the \fBncurses\fR library.
823 The most important ones have been already discussed in detail.
824 .SS CC command-character
825 .PP
826 When set, change occurrences of the command_character
827 (i.e., the \fBcmdch\fP capability)
828 of the loaded terminfo entries to the value of this variable.
829 Very few terminfo entries provide this feature.
830 .PP
831 Because this name is also used in development environments to represent
832 the C compiler's name, \fBncurses\fR ignores it if it does not happen to
833 be a single character.
834 .SS BAUDRATE
835 .PP
836 The debugging library checks this environment variable when the application
837 has redirected output to a file.
838 The variable's numeric value is used for the baudrate.
839 If no value is found, \fBncurses\fR uses 9600.
840 This allows testers to construct repeatable test-cases
841 that take into account costs that depend on baudrate.
842 .SS COLUMNS
843 .PP
844 Specify the width of the screen in characters.
845 Applications running in a windowing environment usually are able to
846 obtain the width of the window in which they are executing.
847 If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available,
848 \fBncurses\fR uses the size which may be specified in the terminfo database
849 (i.e., the \fBcols\fR capability).
850 .PP
851 It is important that your application use a correct size for the screen.
852 This is not always possible because your application may be
853 running on a host which does not honor NAWS (Negotiations About Window
854 Size), or because you are temporarily running as another user.
855 However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
856 use of the screen size obtained from the operating system.
857 .PP
858 Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently.
859 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
860 e.g., xterm which commonly specifies a 65 line screen.
861 For best results, \fBlines\fR and \fBcols\fR should not be specified in
862 a terminal description for terminals which are run as emulations.
863 .PP
864 Use the \fBuse_env\fR function to disable all use of external environment
865 (but not including system calls) to determine the screen size.
866 Use the \fBuse_tioctl\fR function to update \fBCOLUMNS\fP or \fBLINES\fP
867 to match the screen size obtained from system calls or the terminal database.
868 .SS ESCDELAY
869 .PP
870 Specifies the total time, in milliseconds, for which ncurses will
871 await a character sequence, e.g., a function key.
872 The default value, 1000 milliseconds, is enough for most uses.
873 However, it is made a variable to accommodate unusual applications.
874 .PP
875 The most common instance where you may wish to change this value
876 is to work with slow hosts, e.g., running on a network.
877 If the host cannot read characters rapidly enough, it will have the same
878 effect as if the terminal did not send characters rapidly enough.
879 The library will still see a timeout.
880 .PP
881 Note that xterm mouse events are built up from character sequences
882 received from the xterm.
883 If your application makes heavy use of multiple-clicking, you may
884 wish to lengthen this default value because the timeout applies
885 to the composed multi-click event as well as the individual clicks.
886 .PP
887 In addition to the environment variable,
888 this implementation provides a global variable with the same name.
889 Portable applications should not rely upon the presence of ESCDELAY
890 in either form,
891 but setting the environment variable rather than the global variable
892 does not create problems when compiling an application.
893 .SS HOME
894 Tells \fBncurses\fR where your home directory is.
895 That is where it may read and write auxiliary terminal descriptions:
896 .NS
897 $HOME/.termcap
898 $HOME/.terminfo
899 .NE
900 .SS LINES
901 .PP
902 Like COLUMNS, specify the height of the screen in characters.
903 See COLUMNS for a detailed description.
904 .SS MOUSE_BUTTONS_123
905 .PP
906 This applies only to the OS/2 EMX port.
907 It specifies the order of buttons on the mouse.
908 OS/2 numbers a 3-button mouse inconsistently from other
909 platforms:
910 .NS
911 1 = left
912 .br
913 2 = right
914 .br
915 3 = middle.
916 .NE
917 .PP
918 This variable lets you customize the mouse.
919 The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
920 If it is not specified, \fBncurses\fR uses 132.
921 .SS NCURSES_ASSUMED_COLORS
922 .PP
923 Override the compiled-in assumption that the
924 terminal's default colors are white-on-black
925 (see \fBdefault_colors\fR(3X)).
926 You may set the foreground and background color values with this environment
927 variable by proving a 2-element list: foreground,background.
928 For example, to tell ncurses to not assume anything
929 about the colors, set this to "\-1,\-1".
930 To make it green-on-black, set it to "2,0".
931 Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
932 .SS NCURSES_CONSOLE2
933 This applies only to the MinGW port of ncurses.
934 .PP
935 The \fBConsole2\fP program's handling of the Microsoft Console API call
936 \fBCreateConsoleScreenBuffer\fP is defective.
937 Applications which use this will hang.
938 However, it is possible to simulate the action of this call by
939 mapping coordinates,
940 explicitly saving and restoring the original screen contents.
941 Setting the environment variable \fBNCGDB\fP has the same effect.
942 .SS NCURSES_GPM_TERMS
943 .PP
944 This applies only to ncurses configured to use the GPM interface.
945 .PP
946 If present,
947 the environment variable is a list of one or more terminal names
948 against which the \fBTERM\fP environment variable is matched.
949 Setting it to an empty value disables the GPM interface;
950 using the built-in support for xterm, etc.
951 .PP
952 If the environment variable is absent,
953 ncurses will attempt to open GPM if \fBTERM\fP contains \*(``linux\*(''.
954 .SS NCURSES_NO_HARD_TABS
955 .PP
956 \fBNcurses\fP may use tabs as part of the cursor movement optimization.
957 In some cases,
958 your terminal driver may not handle these properly.
959 Set this environment variable to disable the feature.
960 You can also adjust your \fBstty\fP settings to avoid the problem.
961 .SS NCURSES_NO_MAGIC_COOKIE
962 .PP
963 Some terminals use a magic-cookie feature which requires special handling
964 to make highlighting and other video attributes display properly.
965 You can suppress the highlighting entirely for these terminals by
966 setting this environment variable.
967 .SS NCURSES_NO_PADDING
968 .PP
969 Most of the terminal descriptions in the terminfo database are written
970 for real \*(``hardware\*('' terminals.
971 Many people use terminal emulators
972 which run in a windowing environment and use curses-based applications.
973 Terminal emulators can duplicate
974 all of the important aspects of a hardware terminal, but they do not
975 have the same limitations.
976 The chief limitation of a hardware terminal from the standpoint
977 of your application is the management of dataflow, i.e., timing.
978 Unless a hardware terminal is interfaced into a terminal concentrator
979 (which does flow control),
980 it (or your application) must manage dataflow, preventing overruns.
981 The cheapest solution (no hardware cost)
982 is for your program to do this by pausing after
983 operations that the terminal does slowly, such as clearing the display.
984 .PP
985 As a result, many terminal descriptions (including the vt100)
986 have delay times embedded.
987 You may wish to use these descriptions,
988 but not want to pay the performance penalty.
989 .PP
990 Set the NCURSES_NO_PADDING environment variable to disable all but mandatory
991 padding.
992 Mandatory padding is used as a part of special control
993 sequences such as \fIflash\fR.
994 .SS NCURSES_NO_SETBUF
995 This setting is obsolete.
996 Before changes
997 .RS 3
998 .bP
999 started with 5.9 patch 20120825
1000 and
1001 .bP
1002 continued
1003 though 5.9 patch 20130126
1004 .RE
1005 .PP
1006 \fBncurses\fR enabled buffered output during terminal initialization.
1007 This was done (as in SVr4 curses) for performance reasons.
1008 For testing purposes, both of \fBncurses\fR and certain applications,
1009 this feature was made optional.
1010 Setting the NCURSES_NO_SETBUF variable
1011 disabled output buffering, leaving the output in the original (usually
1012 line buffered) mode.
1013 .PP
1014 In the current implementation,
1015 ncurses performs its own buffering and does not require this workaround.
1016 It does not modify the buffering of the standard output.
1017 .PP
1018 The reason for the change was to make the behavior for interrupts and
1019 other signals more robust.
1020 One drawback is that certain nonconventional programs would mix
1021 ordinary stdio calls with ncurses calls and (usually) work.
1022 This is no longer possible since ncurses is not using
1023 the buffered standard output but its own output (to the same file descriptor).
1024 As a special case, the low-level calls such as \fBputp\fP still use the
1025 standard output.
1026 But high-level curses calls do not.
1027 .SS NCURSES_NO_UTF8_ACS
1028 .PP
1029 During initialization, the \fBncurses\fR library
1030 checks for special cases where VT100 line-drawing (and the corresponding
1031 alternate character set capabilities) described in the terminfo are known
1032 to be missing.
1033 Specifically, when running in a UTF\-8 locale,
1034 the Linux console emulator and the GNU screen program ignore these.
1035 Ncurses checks the \fBTERM\fP environment variable for these.
1036 For other special cases, you should set this environment variable.
1037 Doing this tells ncurses to use Unicode values which correspond to
1038 the VT100 line-drawing glyphs.
1039 That works for the special cases cited,
1040 and is likely to work for terminal emulators.
1041 .PP
1042 When setting this variable, you should set it to a nonzero value.
1043 Setting it to zero (or to a nonnumber)
1044 disables the special check for \*(``linux\*('' and \*(``screen\*(''.
1045 .PP
1046 As an alternative to the environment variable,
1047 ncurses checks for an extended terminfo capability \fBU8\fP.
1048 This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
1049 For example
1050 .RS 3
1051 .ft CW
1052 .sp
1053 .nf
1054 # linux console, if patched to provide working
1055 # VT100 shift-in/shift-out, with corresponding font.
1056 linux-vt100|linux console with VT100 line-graphics,
1057         U8#0, use=linux,
1058 .sp
1059 # uxterm with vt100Graphics resource set to false
1060 xterm-utf8|xterm relying on UTF-8 line-graphics,
1061         U8#1, use=xterm,
1062 .fi
1063 .ft
1064 .RE
1065 .PP
1066 The name \*(``U8\*('' is chosen to be two characters,
1067 to permit it to be used by applications that use ncurses'
1068 termcap interface.
1069 .SS NCURSES_TRACE
1070 .PP
1071 During initialization, the \fBncurses\fR debugging library
1072 checks the NCURSES_TRACE environment variable.
1073 If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
1074 function, using that value as the argument.
1075 .PP
1076 The argument values, which are defined in \fBcurses.h\fR, provide several
1077 types of information.
1078 When running with traces enabled, your application will write the
1079 file \fBtrace\fR to the current directory.
1080 .PP
1081 See \fBcurs_trace\fP(3X) for more information.
1082 .SS TERM
1083 .PP
1084 Denotes your terminal type.
1085 Each terminal type is distinct, though many are similar.
1086 .PP
1087 \fBTERM\fP is commonly set by terminal emulators to help
1088 applications find a workable terminal description.
1089 Some of those choose a popular approximation, e.g.,
1090 \*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit.
1091 Not infrequently, your application will have problems with that approach,
1092 e.g., incorrect function-key definitions.
1093 .PP
1094 If you set \fBTERM\fP in your environment,
1095 it has no effect on the operation of the terminal emulator.
1096 It only affects the way applications work within the terminal.
1097 Likewise, as a general rule (\fBxterm\fP being a rare exception),
1098 terminal emulators which allow you to
1099 specify \fBTERM\fP as a parameter or configuration value do
1100 not change their behavior to match that setting.
1101 .SS TERMCAP
1102 If the \fBncurses\fR library has been configured with \fItermcap\fR
1103 support, \fBncurses\fR will check for a terminal's description in
1104 termcap form if it is not available in the terminfo database.
1105 .PP
1106 The \fBTERMCAP\fP environment variable contains
1107 either a terminal description (with newlines stripped out),
1108 or a file name telling where the information denoted by
1109 the \fBTERM\fP environment variable exists.
1110 In either case, setting it directs \fBncurses\fR to ignore
1111 the usual place for this information, e.g., /etc/termcap.
1112 .SS TERMINFO
1113 .PP
1114 \fBncurses\fP can be configured to read from multiple terminal databases.
1115 The \fBTERMINFO\fP variable overrides the location for
1116 the default terminal database.
1117 Terminal descriptions (in terminal format) are stored in terminal databases:
1118 .bP
1119 Normally these are stored in a directory tree,
1120 using subdirectories named by the first letter of the terminal names therein.
1121 .IP
1122 This is the scheme used in System V, which legacy Unix systems use,
1123 and the \fBTERMINFO\fP variable is used by \fIcurses\fP applications on those
1124 systems to override the default location of the terminal database.
1125 .bP
1126 If \fBncurses\fP is built to use hashed databases,
1127 then each entry in this list may be the path of a hashed database file, e.g.,
1128 .NS
1129 /usr/share/terminfo.db
1130 .NE
1131 .IP
1132 rather than
1133 .NS
1134 /usr/share/terminfo/
1135 .NE
1136 .IP
1137 The hashed database uses less disk-space and is a little faster than the
1138 directory tree.
1139 However,
1140 some applications assume the existence of the directory tree,
1141 reading it directly
1142 rather than using the terminfo library calls.
1143 .bP
1144 If \fBncurses\fP is built with a support for reading termcap files
1145 directly, then an entry in this list may be the path of a termcap file.
1146 .bP
1147 If the \fBTERMINFO\fP variable begins with
1148 \*(``hex:\*('' or \*(``b64:\*('',
1149 \fBncurses\fP uses the remainder of that variable as a compiled terminal
1150 description.
1151 You might produce the base64 format using \fBinfocmp\fP(1M):
1152 .NS
1153 TERMINFO="$(infocmp -0 -Q2 -q)"
1154 export TERMINFO
1155 .NE
1156 .IP
1157 The compiled description is used if it corresponds to the terminal identified
1158 by the \fBTERM\fP variable.
1159 .PP
1160 Setting \fBTERMINFO\fP is the simplest,
1161 but not the only way to set location of the default terminal database.
1162 The complete list of database locations in order follows:
1163 .RS 3
1164 .bP
1165 the last terminal database to which \fBncurses\fR wrote,
1166 if any, is searched first
1167 .bP
1168 the location specified by the TERMINFO environment variable
1169 .bP
1170 $HOME/.terminfo
1171 .bP
1172 locations listed in the TERMINFO_DIRS environment variable
1173 .bP
1174 one or more locations whose names are configured and compiled into the
1175 ncurses library, i.e.,
1176 .RS 3
1177 .bP
1178 @TERMINFO_DIRS@ (corresponding to the TERMINFO_DIRS variable)
1179 .bP
1180 @TERMINFO@ (corresponding to the TERMINFO variable)
1181 .RE
1182 .RE
1183 .PP
1184 .SS TERMINFO_DIRS
1185 .PP
1186 Specifies a list of locations to search for terminal descriptions.
1187 Each location in the list is a terminal database as described in
1188 the section on the \fBTERMINFO\fP variable.
1189 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1190 .PP
1191 There is no corresponding feature in System V terminfo;
1192 it is an extension developed for \fBncurses\fP.
1193 .SS TERMPATH
1194 .PP
1195 If \fBTERMCAP\fP does not hold a file name then \fBncurses\fR checks
1196 the \fBTERMPATH\fP environment variable.
1197 This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
1198 semicolons on OS/2 EMX.
1199 .PP
1200 If the \fBTERMPATH\fP environment variable is not set,
1201 \fBncurses\fR looks in the files
1202 .NS
1203 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
1204 .NE
1205 .PP
1206 in that order.
1207 .PP
1208 The library may be configured to disregard the following variables when the
1209 current user is the superuser (root), or if the application uses setuid or
1210 setgid permissions:
1211 .NS
1212 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1213 .NE
1214 .SH ALTERNATE CONFIGURATIONS
1215 .PP
1216 Several different configurations are possible,
1217 depending on the configure script options used when building \fBncurses\fP.
1218 There are a few main options whose effects are visible to the applications
1219 developer using \fBncurses\fP:
1220 .TP 5
1221 \-\-disable\-overwrite
1222 The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
1223 .NS
1224 \fB#include <curses.h>\fR
1225 .NE
1226 .IP
1227 This option is used to avoid filename conflicts when \fBncurses\fP
1228 is not the main implementation of curses of the computer.
1229 If \fBncurses\fP is installed disabling overwrite, it puts its headers in
1230 a subdirectory, e.g.,
1231 .NS
1232 \fB#include <ncurses/curses.h>\fR
1233 .NE
1234 .IP
1235 It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
1236 to build executables.
1237 .TP 5
1238 \-\-enable\-widec
1239 The configure script renames the library and
1240 (if the \fB\-\-disable\-overwrite\fP option is used)
1241 puts the header files in a different subdirectory.
1242 All of the library names have a \*(``w\*('' appended to them,
1243 i.e., instead of
1244 .NS
1245 \fB\-lncurses\fR
1246 .NE
1247 .IP
1248 you link with
1249 .NS
1250 \fB\-lncursesw\fR
1251 .NE
1252 .IP
1253 You must also enable the wide-character features in the header file
1254 when compiling for the wide-character library
1255 to use the extended (wide-character) functions.
1256 The symbol which enables these features has changed since XSI Curses, Issue 4:
1257 .RS
1258 .bP
1259 Originally, the wide-character feature required the symbol
1260 \fB_XOPEN_SOURCE_EXTENDED\fP
1261 but that was only valid for XPG4 (1996).
1262 .bP
1263 Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500.
1264 .bP
1265 As of mid-2018,
1266 none of the features in this implementation require a \fB_XOPEN_SOURCE\fP
1267 feature greater than 600.
1268 However, X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1269 .bP
1270 Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP
1271 with the caveat that some other header file than \fBcurses.h\fP
1272 may require a specific value for \fB_XOPEN_SOURCE\fP
1273 (or a system-specific symbol).
1274 .RE
1275 .IP
1276 The \fBcurses.h\fP file which is installed for the wide-character
1277 library is designed to be compatible with the normal library's header.
1278 Only the size of the \fBWINDOW\fP structure differs, and very few
1279 applications require more than a pointer to \fBWINDOW\fPs.
1280 .IP
1281 If the headers are installed allowing overwrite,
1282 the wide-character library's headers should be installed last,
1283 to allow applications to be built using either library
1284 from the same set of headers.
1285 .TP 5
1286 \-\-with\-pthread
1287 The configure script renames the library.
1288 All of the library names have a \*(``t\*('' appended to them
1289 (before any \*(``w\*('' added by \fB\-\-enable\-widec\fP).
1290 .IP
1291 The global variables such as \fBLINES\fP are replaced by macros to
1292 allow read-only access.
1293 At the same time, setter-functions are provided to set these values.
1294 Some applications (very few) may require changes to work with this convention.
1295 .TP 5
1296 \-\-with\-shared
1297 .TP
1298 \-\-with\-normal
1299 .TP
1300 \-\-with\-debug
1301 .TP
1302 \-\-with\-profile
1303 The shared and normal (static) library names differ by their suffixes,
1304 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
1305 The debug and profiling libraries add a \*(``_g\*(''
1306 and a \*(``_p\*('' to the root names respectively,
1307 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
1308 .TP 5
1309 \-\-with\-trace
1310 The \fBtrace\fP function normally resides in the debug library,
1311 but it is sometimes useful to configure this in the shared library.
1312 Configure scripts should check for the function's existence rather
1313 than assuming it is always in the debug library.
1314 .SH FILES
1315 .TP 5
1316 @DATADIR@/tabset
1317 directory containing initialization files for the terminal capability database
1318 @TERMINFO@
1319 terminal capability database
1320 .SH SEE ALSO
1321 \fBterminfo\fR(\*n) and related pages whose names begin
1322 \*(``curs_\*('' for detailed routine descriptions.
1323 .br
1324 \fBcurs_variables\fR(3X)
1325 .br
1326 \fBuser_caps\fP(5) for user-defined capabilities
1327 .SH EXTENSIONS
1328 The \fBncurses\fR library can be compiled with an option (\fB\-DUSE_GETCAP\fR)
1329 that falls back to the old-style /etc/termcap file if the terminal setup code
1330 cannot find a terminfo entry corresponding to \fBTERM\fR.
1331 Use of this feature
1332 is not recommended, as it essentially includes an entire termcap compiler in
1333 the \fBncurses\fR startup code, at significant cost in core and startup cycles.
1334 .PP
1335 The \fBncurses\fR library includes facilities for capturing mouse events on
1336 certain terminals (including xterm).
1337 See the \fBcurs_mouse\fR(3X)
1338 manual page for details.
1339 .PP
1340 The \fBncurses\fR library includes facilities for responding to window
1341 resizing events, e.g., when running in an xterm.
1342 See the \fBresizeterm\fR(3X)
1343 and \fBwresize\fR(3X) manual pages for details.
1344 In addition, the library may be configured with a \fBSIGWINCH\fP handler.
1345 .PP
1346 The \fBncurses\fR library extends the fixed set of function key capabilities
1347 of terminals by allowing the application designer to define additional
1348 key sequences at runtime.
1349 See the \fBdefine_key\fR(3X)
1350 \fBkey_defined\fR(3X),
1351 and \fBkeyok\fR(3X) manual pages for details.
1352 .PP
1353 The \fBncurses\fR library can exploit the capabilities of terminals which
1354 implement the ISO\-6429 SGR 39 and SGR 49 controls, which allow an application
1355 to reset the terminal to its original foreground and background colors.
1356 From the users' perspective, the application is able to draw colored
1357 text on a background whose color is set independently, providing better
1358 control over color contrasts.
1359 See the \fBdefault_colors\fR(3X) manual page for details.
1360 .PP
1361 The \fBncurses\fR library includes a function for directing application output
1362 to a printer attached to the terminal device.
1363 See the \fBcurs_print\fR(3X) manual page for details.
1364 .SH PORTABILITY
1365 The \fBncurses\fR library is intended to be BASE-level conformant with XSI
1366 Curses.
1367 The EXTENDED XSI Curses functionality
1368 (including color support) is supported.
1369 .PP
1370 A small number of local differences (that is, individual differences between
1371 the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
1372 sections of the library man pages.
1373 .SS Error checking
1374 .PP
1375 In many cases, X/Open Curses is vague about error conditions,
1376 omitting some of the SVr4 documentation.
1377 .PP
1378 Unlike other implementations, this one checks parameters such as pointers
1379 to WINDOW structures to ensure they are not null.
1380 The main reason for providing this behavior is to guard against programmer
1381 error.
1382 The standard interface does not provide a way for the library
1383 to tell an application which of several possible errors were detected.
1384 Relying on this (or some other) extension will adversely affect the
1385 portability of curses applications.
1386 .SS Extensions versus portability
1387 .PP
1388 Most of the extensions provided by ncurses have not been standardized.
1389 Some have been incorporated into other implementations, such as
1390 PDCurses or NetBSD curses.
1391 Here are a few to consider:
1392 .bP
1393 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.
1394 See the \fBcurs_getch\fR(3X) manual page for details.
1395 .bP
1396 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.
1397 See the \fBcurs_slk\fR(3X) manual page for details.
1398 .bP
1399 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
1400 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
1401 part of XPG4, nor are they present in SVr4.
1402 See the \fBcurs_mouse\fR(3X) manual page for details.
1403 .bP
1404 The routine \fBmcprint\fR was not present in any previous curses implementation.
1405 See the \fBcurs_print\fR(3X) manual page for details.
1406 .bP
1407 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.
1408 See the \fBwresize\fR(3X) manual page for details.
1409 .bP
1410 The WINDOW structure's internal details can be hidden from application
1411 programs.
1412 See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc.
1413 .bP
1414 This implementation can be configured to provide rudimentary support
1415 for multi-threaded applications.
1416 See \fBcurs_threads\fR(3X) for details.
1417 .bP
1418 This implementation can also be configured to provide a set of functions which
1419 improve the ability to manage multiple screens.
1420 See \fBcurs_sp_funcs\fR(3X) for details.
1421 .SS Padding differences
1422 .PP
1423 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
1424 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
1425 bits in the UNIX tty driver.
1426 In this implementation, all padding is done by sending NUL bytes.
1427 This method is slightly more expensive, but narrows the interface
1428 to the UNIX kernel significantly and increases the package's portability
1429 correspondingly.
1430 .SS Header files
1431 The header file \fB<curses.h>\fR automatically includes the header files
1432 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
1433 .PP
1434 X/Open Curses has more to say,
1435 but does not finish the story:
1436 .RS 4
1437 .PP
1438 The inclusion of <curses.h> may make visible all symbols
1439 from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
1440 .RE
1441 .PP
1442 Here is a more complete story:
1443 .bP
1444 Starting with BSD curses, all implementations have included <stdio.h>.
1445 .IP
1446 BSD curses included <curses.h> and <unctrl.h> from an internal header
1447 "curses.ext" ("ext" was a short name for \fIexterns\fP).
1448 .IP
1449 BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP),
1450 but nothing in <curses.h> itself relied upon <stdio.h>.
1451 .bP
1452 SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>.
1453 That is, the function prototype uses \fBFILE\fP.
1454 .IP
1455 SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>.
1456 .IP
1457 X/Open Curses documents all three of these functions.
1458 .IP
1459 SVr4 curses and X/Open Curses do not require the developer to
1460 include <stdio.h> before including <curses.h>.
1461 Both document curses showing <curses.h> as the only required header.
1462 .IP
1463 As a result, standard <curses.h> will always include <stdio.h>.
1464 .bP
1465 X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>.
1466 .IP
1467 As noted in \fBcurs_util\fP(3X), ncurses includes <unctrl.h> from
1468 <curses.h> (like SVr4).
1469 .bP
1470 X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX:
1471 .IP
1472 HP-UX curses includes <term.h> from <curses.h>
1473 to declare \fBsetupterm\fP in curses.h,
1474 but ncurses (and Solaris curses) do not.
1475 .IP
1476 AIX curses includes <term.h> and <termios.h>.
1477 Again, ncurses (and Solaris curses) do not.
1478 .bP
1479 X/Open says that <curses.h> \fImay\fP include <term.h>,
1480 but there is no requirement that it do that.
1481 .IP
1482 Some programs use functions declared in both <curses.h> and <term.h>,
1483 and must include both headers in the same module.
1484 Very old versions of AIX curses required including <curses.h>
1485 before including <term.h>.
1486 .IP
1487 Because ncurses header files include the headers needed to
1488 define datatypes used in the headers,
1489 ncurses header files can be included in any order.
1490 But for portability, you should include <curses.h> before <term.h>.
1491 .bP
1492 X/Open Curses says \fI"may make visible"\fP
1493 because including a header file does not necessarily make all symbols
1494 in it visible (there are ifdef's to consider).
1495 .IP
1496 For instance, in ncurses <wchar.h> \fImay\fP be included if
1497 the proper symbol is defined, and if ncurses is configured for
1498 wide-character support.
1499 If the header is included, its symbols may be made visible.
1500 That depends on the value used for \fB_XOPEN_SOURCE\fP
1501 feature test macro.
1502 .bP
1503 X/Open Curses documents one required header,
1504 in a special case: <stdarg.h> before <curses.h> to prototype
1505 the \fBvw_printw\fP and \fBvw_scanw\fP functions
1506 (as well as the obsolete
1507 the \fBvwprintw\fP and \fBvwscanw\fP functions).
1508 Each of those uses a \fBva_list\fP parameter.
1509 .IP
1510 The two obsolete functions were introduced in SVr3.
1511 The other functions were introduced in X/Open Curses.
1512 In between, SVr4 curses provided for the possibility that
1513 an application might include either <varargs.h> or <stdarg.h>.
1514 Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP
1515 parameter.
1516 Later, a special type (defined in <stdio.h>) was introduced,
1517 to allow for compiler type-checking.
1518 That special type is always available,
1519 because <stdio.h> is always included by <curses.h>.
1520 .IP
1521 None of the X/Open Curses implementations require an application
1522 to include <stdarg.h> before <curses.h> because they either
1523 have allowed for a special type, or (like ncurses) include <stdarg.h>
1524 directly to provide a portable interface.
1525 .SH NOTES
1526 .PP
1527 If standard output from a \fBncurses\fR program is re-directed to something
1528 which is not a tty, screen updates will be directed to standard error.
1529 This was an undocumented feature of AT&T System V Release 3 curses.
1530 .SH AUTHORS
1531 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1532 Based on pcurses by Pavel Curtis.