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