ncurses 5.9 - patch 20120303
[ncurses.git] / man / ncurses.3x
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright (c) 1998-2010,2011 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.106 2011/12/17 23:19:59 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 \fB@TPUT@ init\fR command
112 after the shell environment variable \fBTERM\fR has been exported.
113 \fB@TSET@(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 As a general rule, routines check for null pointers passed as parameters,
738 and handle this as an error.
739 .PP
740 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
741 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.
742 The return values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
743 \fBgetmaxyx\fR are undefined (i.e., these should not be used as the
744 right-hand side of assignment statements).
745 .PP
746 Routines that return pointers return \fBNULL\fR on error.
747 .SH ENVIRONMENT
748 The following environment symbols are useful for customizing the
749 runtime behavior of the \fBncurses\fR library.
750 The most important ones have been already discussed in detail.
751 .TP 5
752 BAUDRATE
753 The debugging library checks this environment symbol when the application
754 has redirected output to a file.
755 The symbol's numeric value is used for the baudrate.
756 If no value is found, \fBncurses\fR uses 9600.
757 This allows testers to construct repeatable test-cases
758 that take into account costs that depend on baudrate.
759 .TP 5
760 CC
761 When set, change occurrences of the command_character
762 (i.e., the \fBcmdch\fP capability)
763 of the loaded terminfo entries to the value of this symbol.
764 Very few terminfo entries provide this feature.
765 .IP
766 Because this name is also used in development environments to represent
767 the C compiler's name, \fBncurses\fR ignores it if it does not happen to
768 be a single character.
769 .TP 5
770 COLUMNS
771 Specify the width of the screen in characters.
772 Applications running in a windowing environment usually are able to
773 obtain the width of the window in which they are executing.
774 If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available,
775 \fBncurses\fR uses the size which may be specified in the terminfo database
776 (i.e., the \fBcols\fR capability).
777 .IP
778 It is important that your application use a correct size for the screen.
779 This is not always possible because your application may be
780 running on a host which does not honor NAWS (Negotiations About Window
781 Size), or because you are temporarily running as another user.
782 However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
783 use of the screen size obtained from the operating system.
784 .IP
785 Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently.
786 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
787 e.g., xterm which commonly specifies a 65 line screen.
788 For best results, \fBlines\fR and \fBcols\fR should not be specified in
789 a terminal description for terminals which are run as emulations.
790 .IP
791 Use the \fBuse_env\fR function to disable all use of external environment
792 (including system calls) to determine the screen size.
793 .TP 5
794 ESCDELAY
795 Specifies the total time, in milliseconds, for which ncurses will
796 await a character sequence, e.g., a function key.
797 The default value, 1000 milliseconds, is enough for most uses.
798 However, it is made a variable to accommodate unusual applications.
799 .IP
800 The most common instance where you may wish to change this value
801 is to work with slow hosts, e.g., running on a network.
802 If the host cannot read characters rapidly enough, it will have the same
803 effect as if the terminal did not send characters rapidly enough.
804 The library will still see a timeout.
805 .IP
806 Note that xterm mouse events are built up from character sequences
807 received from the xterm.
808 If your application makes heavy use of multiple-clicking, you may
809 wish to lengthen this default value because the timeout applies
810 to the composed multi-click event as well as the individual clicks.
811 .IP
812 In addition to the environment variable,
813 this implementation provides a global variable with the same name.
814 Portable applications should not rely upon the presence of ESCDELAY
815 in either form,
816 but setting the environment variable rather than the global variable
817 does not create problems when compiling an application.
818 .TP 5
819 HOME
820 Tells \fBncurses\fR where your home directory is.
821 That is where it may read and write auxiliary terminal descriptions:
822 .IP
823 $HOME/.termcap
824 .br
825 $HOME/.terminfo
826 .TP 5
827 LINES
828 Like COLUMNS, specify the height of the screen in characters.
829 See COLUMNS for a detailed description.
830 .TP 5
831 MOUSE_BUTTONS_123
832 This applies only to the OS/2 EMX port.
833 It specifies the order of buttons on the mouse.
834 OS/2 numbers a 3-button mouse inconsistently from other
835 platforms:
836 .sp
837 1 = left
838 .br
839 2 = right
840 .br
841 3 = middle.
842 .sp
843 This symbol lets you customize the mouse.
844 The symbol must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
845 If it is not specified, \fBncurses\fR uses 132.
846 .TP 5
847 NCURSES_ASSUMED_COLORS
848 Override the compiled-in assumption that the
849 terminal's default colors are white-on-black
850 (see \fBdefault_colors\fR(3X)).
851 You may set the foreground and background color values with this environment
852 variable by proving a 2-element list: foreground,background.
853 For example, to tell ncurses to not assume anything
854 about the colors, set this to "\-1,\-1".
855 To make it green-on-black, set it to "2,0".
856 Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
857 .TP 5
858 NCURSES_GPM_TERMS
859 This applies only to ncurses configured to use the GPM interface.
860 .IP
861 If present,
862 the environment variable is a list of one or more terminal names
863 against which the TERM environment variable is matched.
864 Setting it to an empty value disables the GPM interface;
865 using the built-in support for xterm, etc.
866 .IP
867 If the environment variable is absent,
868 ncurses will attempt to open GPM if TERM contains "linux".
869 .TP 5
870 NCURSES_NO_HARD_TABS
871 \fBNcurses\fP may use tabs as part of the cursor movement optimization.
872 In some cases,
873 your terminal driver may not handle these properly.
874 Set this environment variable to disable the feature.
875 You can also adjust your \fBstty\fP settings to avoid the problem.
876 .TP 5
877 NCURSES_NO_MAGIC_COOKIES
878 Some terminals use a magic-cookie feature which requires special handling
879 to make highlighting and other video attributes display properly.
880 You can suppress the highlighting entirely for these terminals by
881 setting this environment variable.
882 .TP 5
883 NCURSES_NO_PADDING
884 Most of the terminal descriptions in the terminfo database are written
885 for real "hardware" terminals.
886 Many people use terminal emulators
887 which run in a windowing environment and use curses-based applications.
888 Terminal emulators can duplicate
889 all of the important aspects of a hardware terminal, but they do not
890 have the same limitations.
891 The chief limitation of a hardware terminal from the standpoint
892 of your application is the management of dataflow, i.e., timing.
893 Unless a hardware terminal is interfaced into a terminal concentrator
894 (which does flow control),
895 it (or your application) must manage dataflow, preventing overruns.
896 The cheapest solution (no hardware cost)
897 is for your program to do this by pausing after
898 operations that the terminal does slowly, such as clearing the display.
899 .IP
900 As a result, many terminal descriptions (including the vt100)
901 have delay times embedded.
902 You may wish to use these descriptions,
903 but not want to pay the performance penalty.
904 .IP
905 Set the NCURSES_NO_PADDING symbol to disable all but mandatory
906 padding.
907 Mandatory padding is used as a part of special control
908 sequences such as \fIflash\fR.
909 .TP 5
910 NCURSES_NO_SETBUF
911 Normally \fBncurses\fR enables buffered output during terminal initialization.
912 This is done (as in SVr4 curses) for performance reasons.
913 For testing purposes, both of \fBncurses\fR and certain applications,
914 this feature is made optional.
915 Setting the NCURSES_NO_SETBUF variable
916 disables output buffering, leaving the output in the original (usually
917 line buffered) mode.
918 .TP 5
919 NCURSES_NO_UTF8_ACS
920 During initialization, the \fBncurses\fR library
921 checks for special cases where VT100 line-drawing (and the corresponding
922 alternate character set capabilities) described in the terminfo are known
923 to be missing.
924 Specifically, when running in a UTF\-8 locale,
925 the Linux console emulator and the GNU screen program ignore these.
926 Ncurses checks the TERM environment variable for these.
927 For other special cases, you should set this environment variable.
928 Doing this tells ncurses to use Unicode values which correspond to
929 the VT100 line-drawing glyphs.
930 That works for the special cases cited,
931 and is likely to work for terminal emulators.
932 .IP
933 When setting this variable, you should set it to a nonzero value.
934 Setting it to zero (or to a nonnumber)
935 disables the special check for "linux" and "screen".
936 .IP
937 As an alternative to the environment variable,
938 ncurses checks for an extended terminfo capability \fBU8\fP.
939 This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
940 For example
941 .RS 5
942 .sp
943 .nf
944 # linux console, if patched to provide working
945 # VT100 shift-in/shift-out, with corresponding font.
946 linux-vt100|linux console with VT100 line-graphics,
947         U8#0, use=linux,
948 .sp
949 # uxterm with vt100Graphics resource set to false
950 xterm-utf8|xterm relying on UTF-8 line-graphics,
951         U8#1, use=xterm,
952 .fi
953 .RE
954 .IP
955 The name "U8" is chosen to be two characters,
956 to permit it to be used by applications that use ncurses'
957 termcap interface.
958 .TP 5
959 NCURSES_TRACE
960 During initialization, the \fBncurses\fR debugging library
961 checks the NCURSES_TRACE symbol.
962 If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
963 function, using that value as the argument.
964 .IP
965 The argument values, which are defined in \fBcurses.h\fR, provide several
966 types of information.
967 When running with traces enabled, your application will write the
968 file \fBtrace\fR to the current directory.
969 .TP 5
970 TERM
971 Denotes your terminal type.
972 Each terminal type is distinct, though many are similar.
973 .TP 5
974 TERMCAP
975 If the \fBncurses\fR library has been configured with \fItermcap\fR
976 support, \fBncurses\fR will check for a terminal's description in
977 termcap form if it is not available in the terminfo database.
978 .IP
979 The TERMCAP symbol contains either a terminal description (with
980 newlines stripped out),
981 or a file name telling where the information denoted by the TERM symbol exists.
982 In either case, setting it directs \fBncurses\fR to ignore
983 the usual place for this information, e.g., /etc/termcap.
984 .TP 5
985 TERMINFO
986 Overrides the directory in which \fBncurses\fR searches for your terminal
987 description.
988 This is the simplest, but not the only way to change the list of directories.
989 The complete list of directories in order follows:
990 .RS
991 .bP
992 the last directory to which \fBncurses\fR wrote, if any, is searched first
993 .bP
994 the directory specified by the TERMINFO symbol
995 .bP
996 $HOME/.terminfo
997 .bP
998 directories listed in the TERMINFO_DIRS symbol
999 .bP
1000 one or more directories whose names are configured and compiled into the
1001 ncurses library, e.g.,
1002 @TERMINFO@
1003 .RE
1004 .TP 5
1005 TERMINFO_DIRS
1006 Specifies a list of directories to search for terminal descriptions.
1007 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1008 All of the terminal descriptions are in terminfo form, which makes
1009 a subdirectory named for the first letter of the terminal names therein.
1010 .IP
1011 If \fBncurses\fP is built with a hashed database,
1012 then each entry in this list can also be the path of the corresponding
1013 database file.
1014 .IP
1015 If \fBncurses\fP is built with a support for reading termcap files
1016 directly, then an entry in this list may be the path of a termcap file.
1017 .TP 5
1018 TERMPATH
1019 If TERMCAP does not hold a file name then \fBncurses\fR checks
1020 the TERMPATH symbol.
1021 This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1022 If the TERMPATH symbol is not set, \fBncurses\fR looks in the files
1023 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
1024 .PP
1025 The library may be configured to disregard the following variables when the
1026 current user is the superuser (root), or if the application uses setuid or
1027 setgid permissions:
1028 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1029 .SH ALTERNATE CONFIGURATIONS
1030 Several different configurations are possible,
1031 depending on the configure script options used when building \fBncurses\fP.
1032 There are a few main options whose effects are visible to the applications
1033 developer using \fBncurses\fP:
1034 .TP 5
1035 \-\-disable\-overwrite
1036 The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
1037 .RS
1038 .sp
1039 \fB#include <curses.h>\fR
1040 .RE
1041 .IP
1042 This option is used to avoid filename conflicts when \fBncurses\fP
1043 is not the main implementation of curses of the computer.
1044 If \fBncurses\fP is installed disabling overwrite, it puts its headers in
1045 a subdirectory, e.g.,
1046 .RS
1047 .sp
1048 \fB#include <ncurses/curses.h>\fR
1049 .RE
1050 .IP
1051 It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
1052 to build executables.
1053 .TP 5
1054 \-\-enable\-widec
1055 The configure script renames the library and (if the \fB\-\-disable\-overwrite\fP
1056 option is used) puts the header files in a different subdirectory.
1057 All of the library names have a "w" appended to them,
1058 i.e., instead of
1059 .RS
1060 .sp
1061 \fB\-lncurses\fR
1062 .RE
1063 .IP
1064 you link with
1065 .RS
1066 .sp
1067 \fB\-lncursesw\fR
1068 .RE
1069 .IP
1070 You must also define \fB_XOPEN_SOURCE_EXTENDED\fP when compiling for the
1071 wide-character library to use the extended (wide-character) functions.
1072 The \fBcurses.h\fP file which is installed for the wide-character
1073 library is designed to be compatible with the normal library's header.
1074 Only the size of the \fBWINDOW\fP structure differs, and very few
1075 applications require more than a pointer to \fBWINDOW\fPs.
1076 If the headers are installed allowing overwrite,
1077 the wide-character library's headers should be installed last,
1078 to allow applications to be built using either library
1079 from the same set of headers.
1080 .TP 5
1081 \-\-with\-shared
1082 .TP
1083 \-\-with\-normal
1084 .TP
1085 \-\-with\-debug
1086 .TP
1087 \-\-with\-profile
1088 The shared and normal (static) library names differ by their suffixes,
1089 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
1090 The debug and profiling libraries add a "_g" and a "_p" to the root
1091 names respectively,
1092 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
1093 .TP 5
1094 \-\-with\-trace
1095 The \fBtrace\fP function normally resides in the debug library,
1096 but it is sometimes useful to configure this in the shared library.
1097 Configure scripts should check for the function's existence rather
1098 than assuming it is always in the debug library.
1099 .SH FILES
1100 .TP 5
1101 @DATADIR@/tabset
1102 directory containing initialization files for the terminal capability database
1103 @TERMINFO@
1104 terminal capability database
1105 .SH SEE ALSO
1106 \fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine
1107 descriptions.
1108 .br
1109 \fBcurs_variables\fR(3X) 
1110 .SH EXTENSIONS
1111 The \fBncurses\fR library can be compiled with an option (\fB\-DUSE_GETCAP\fR)
1112 that falls back to the old-style /etc/termcap file if the terminal setup code
1113 cannot find a terminfo entry corresponding to \fBTERM\fR.
1114 Use of this feature
1115 is not recommended, as it essentially includes an entire termcap compiler in
1116 the \fBncurses\fR startup code, at significant cost in core and startup cycles.
1117 .PP
1118 The \fBncurses\fR library includes facilities for capturing mouse events on
1119 certain terminals (including xterm).
1120 See the \fBcurs_mouse\fR(3X)
1121 manual page for details.
1122 .PP
1123 The \fBncurses\fR library includes facilities for responding to window
1124 resizing events, e.g., when running in an xterm.
1125 See the \fBresizeterm\fR(3X)
1126 and \fBwresize\fR(3X) manual pages for details.
1127 In addition, the library may be configured with a SIGWINCH handler.
1128 .PP
1129 The \fBncurses\fR library extends the fixed set of function key capabilities
1130 of terminals by allowing the application designer to define additional
1131 key sequences at runtime.
1132 See the \fBdefine_key\fR(3X)
1133 \fBkey_defined\fR(3X),
1134 and \fBkeyok\fR(3X) manual pages for details.
1135 .PP
1136 The \fBncurses\fR library can exploit the capabilities of terminals which
1137 implement the ISO\-6429 SGR 39 and SGR 49 controls, which allow an application
1138 to reset the terminal to its original foreground and background colors.
1139 From the users' perspective, the application is able to draw colored
1140 text on a background whose color is set independently, providing better
1141 control over color contrasts.
1142 See the \fBdefault_colors\fR(3X) manual page for details.
1143 .PP
1144 The \fBncurses\fR library includes a function for directing application output
1145 to a printer attached to the terminal device.
1146 See the \fBcurs_print\fR(3X) manual page for details.
1147 .SH PORTABILITY
1148 The \fBncurses\fR library is intended to be BASE-level conformant with XSI
1149 Curses.
1150 The EXTENDED XSI Curses functionality
1151 (including color support) is supported.
1152 .PP
1153 A small number of local differences (that is, individual differences between
1154 the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
1155 sections of the library man pages.
1156 .PP
1157 Unlike other implementations, this one checks parameters such as pointers
1158 to WINDOW structures to ensure they are not null.
1159 The main reason for providing this behavior is to guard against programmer
1160 error.
1161 The standard interface does not provide a way for the library
1162 to tell an application which of several possible errors were detected.
1163 Relying on this (or some other) extension will adversely affect the
1164 portability of curses applications.
1165 .PP
1166 This implementation also contains several extensions:
1167 .bP
1168 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.
1169 See the \fBcurs_getch\fR(3X) manual page for details.
1170 .bP
1171 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.
1172 See the \fBcurs_slk\fR(3X) manual page for details.
1173 .bP
1174 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
1175 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
1176 part of XPG4, nor are they present in SVr4.
1177 See the \fBcurs_mouse\fR(3X) manual page for details.
1178 .bP
1179 The routine \fBmcprint\fR was not present in any previous curses implementation.
1180 See the \fBcurs_print\fR(3X) manual page for details.
1181 .bP
1182 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.
1183 See the \fBwresize\fR(3X) manual page for details.
1184 .bP
1185 The WINDOW structure's internal details can be hidden from application
1186 programs.
1187 See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc.
1188 .bP
1189 This implementation can be configured to provide rudimentary support
1190 for multi-threaded applications.
1191 See \fBcurs_threads\fR(3X) for details.
1192 .bP
1193 This implementation can also be configured to provide a set of functions which
1194 improve the ability to manage multiple screens.
1195 See \fBcurs_sp_funcs\fR(3X) for details.
1196 .PP
1197 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
1198 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
1199 bits in the UNIX tty driver.
1200 In this implementation, all padding is done by sending NUL bytes.
1201 This method is slightly more expensive, but narrows the interface
1202 to the UNIX kernel significantly and increases the package's portability
1203 correspondingly.
1204 .SH NOTES
1205 The header file \fB<curses.h>\fR automatically includes the header files
1206 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
1207 .PP
1208 If standard output from a \fBncurses\fR program is re-directed to something
1209 which is not a tty, screen updates will be directed to standard error.
1210 This was an undocumented feature of AT&T System V Release 3 curses.
1211 .SH AUTHORS
1212 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1213 Based on pcurses by Pavel Curtis.