man/ncurses.3x

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