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