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