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