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