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