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