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