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