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