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