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