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