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