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