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