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