man/ncurses.3x

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