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