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