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