man/ncurses.3x

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright 2018-2023,2024 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.207 2024/04/14 00:34:00 tom Exp $
  32 .TH ncurses 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "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 .
  44 .de bP
  45 .ie n  .IP \(bu 4
  46 .el    .IP \(bu 2
  47 ..
  48 .
  49 .ds d @TERMINFO@
  50 .SH NAME
  51 \fB\%ncurses\fP \-
  52 character-cell terminal interface with optimized output
  53 .SH SYNOPSIS
  54 .nf
  55 \fB#include <curses.h>
  56 .fi
  57 .SH DESCRIPTION
  58 The \*(``new curses\*('' library offers the programmer a
  59 terminal-independent means of reading keyboard and mouse input and
  60 updating character-cell terminals with output optimized to minimize
  61 screen updates.
  62 .I \%ncurses
  63 replaces the
  64 .I curses
  65 libraries from
  66 System V Release 4 Unix (\*(``SVr4\*('')
  67 and
  68 4.4BSD Unix,
  69 the development of which ceased in the 1990s.
  70 This describes \fI\%ncurses\fP
  71 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
  72 .PP
  73 .I \%ncurses
  74 permits control of the terminal screen's contents;
  75 abstraction and subdivision thereof with
  76 .I windows
  77 and
  78 .IR pads ;
  79 the reading of terminal input;
  80 control of terminal input and output options;
  81 environment query routines;
  82 color manipulation;
  83 the definition and use of
  84 .I "soft label"
  85 keys;
  86 .I \%term\%info
  87 capability access;
  88 a
  89 .I termcap
  90 compatibility interface;
  91 and an abstraction of the system's API for manipulating the terminal
  92 (such as \fI\%termios\fP(3)).
  93 .PP
  94 .I \%ncurses
  95 implements the standard interface described by
  96 X/Open Curses Issue\ 7.
  97 In many behavioral details not standardized by X/Open,
  98 .I \%ncurses
  99 emulates the
 100 .I curses
 101 library of SVr4 and provides numerous useful extensions.
 102 .PP
 103 .I \%ncurses
 104 man pages employ several sections to clarify matters of usage and
 105 interoperability with other
 106 .I curses
 107 implementations.
 108 .bP
 109 \*(``NOTES\*('' describes issues and caveats of which any user of the
 110 .I \%ncurses
 111 API should be aware,
 112 such as limitations on the size of an underlying integral type or the
 113 availability of a preprocessor macro exclusive of a function definition
 114 (which prevents its address from being taken).
 115 This section also describes implementation details that will be
 116 significant to the programmer but which are not standardized.
 117 .bP
 118 \*(``EXTENSIONS\*('' presents
 119 .I \%ncurses
 120 innovations beyond the X/Open Curses standard and/or the SVr4
 121 .I curses
 122 implementation.
 123 They are termed
 124 .I extensions
 125 to indicate that they cannot be implemented solely by using the library
 126 API,
 127 but require access to the library's internal state.
 128 .bP
 129 \*(``PORTABILITY\*('' discusses matters
 130 (beyond the exercise of extensions)
 131 that should be considered when writing to a
 132 .I curses
 133 standard,
 134 or for multiple implementations.
 135 .bP
 136 \*(``HISTORY\*('' examines points of detail in
 137 .I \%ncurses
 138 and other
 139 .I curses
 140 implementations over the decades of their development,
 141 particularly where precedent or inertia have frustrated better design
 142 (and,
 143 in a few cases,
 144 where such inertia has been overcome).
 145 .PP
 146 A
 147 .I curses
 148 application must be linked with the library;
 149 use the
 150 .B \-lncurses
 151 option to your compiler or linker.
 152 A debugging version of the library may be available;
 153 if so,
 154 link with it using
 155 .BR \-lncurses_g .
 156 (Your system integrator may have installed these libraries such that you
 157 can use the options
 158 .B \-lcurses
 159 and
 160 .BR \-lcurses_g ,
 161 respectively.)
 162 The
 163 .I \%ncurses_g
 164 library generates trace logs
 165 (in a file called
 166 .I \%trace
 167 in the current directory)
 168 that describe
 169 .I \%ncurses
 170 actions.
 171 See section \*(``ALTERNATE CONFIGURATIONS\*('' below.
 172 .SS "Application Structure"
 173 A
 174 .I curses
 175 application uses information from the system locale;
 176 \fI\%setlocale\fP(3) prepares it for
 177 .I curses
 178 library calls.
 179 .PP
 180 .RS 4
 181 .EX
 182 setlocale(LC_ALL, "");
 183 .EE
 184 .RE
 185 .PP
 186 If the locale is not thus initialized,
 187 the library assumes that characters are printable as in ISO\ 8859-1,
 188 to work with certain legacy programs.
 189 You should initialize the locale;
 190 do not expect consistent behavior from the library when the locale has
 191 not been set up.
 192 .PP
 193 \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X)
 194 must be called to initialize
 195 .I curses
 196 before use of any functions that deal with windows and screens.
 197 .PP
 198 To get character-at-a-time input without echoing\(emmost interactive,
 199 screen-oriented programs want this\(emuse the following sequence.
 200 .PP
 201 .RS 4
 202 .EX
 203 initscr(); cbreak(); noecho();
 204 .EE
 205 .RE
 206 .PP
 207 Most applications perform further setup as follows.
 208 .PP
 209 .RS 4
 210 .EX
 211 intrflush(stdscr, FALSE);
 212 keypad(stdscr, TRUE);
 213 .EE
 214 .RE
 215 .PP
 216 A
 217 .I curses
 218 program then often enters an event loop of some sort.
 219 Call \fB\%endwin\fP(3X) before exiting.
 220 .SS Overview
 221 A
 222 .I curses
 223 library abstracts the terminal screen by representing all or part of it
 224 as a
 225 .I \%WINDOW
 226 data structure.
 227 A
 228 .I window
 229 is a rectangular grid of character cells,
 230 addressed by row and column coordinates
 231 .RI ( y ,
 232 .IR x ),
 233 with the upper left corner as (0, 0).
 234 A window called
 235 .BR \%stdscr ,
 236 the same size as the terminal screen,
 237 is always available.
 238 Create others with \fB\%newwin\fP(3X).
 239 .PP
 240 A
 241 .I curses
 242 library does not manage overlapping windows
 243 (but see below).
 244 You can either use
 245 .B \%stdscr
 246 to manage one screen-filling window,
 247 or tile the screen into non-overlapping windows and not use
 248 .B \%stdscr
 249 at all.
 250 Mixing the two approaches will result in unpredictable and undesired
 251 effects.
 252 .PP
 253 Functions permit manipulation of a window and the
 254 .I cursor
 255 identifying the cell within it at which the next output operation will
 256 occur.
 257 Among those,
 258 the most basic are \fB\%move\fP(3X) and \fB\%addch\fP(3X):
 259 these place the cursor and write a character to
 260 .BR \%stdscr ,
 261 respectively.
 262 .PP
 263 Frequent changes to the terminal screen can cause unpleasant flicker or
 264 inefficient use of the communication channel to the device,
 265 so the library does not generally update it automatically.
 266 Therefore,
 267 after using
 268 .I curses
 269 functions to accumulate a set of desired updates that make sense to
 270 present together,
 271 call \fB\%refresh\fP(3X) to tell the library to make the user's screen
 272 look like \fBstdscr\fP.
 273 The library
 274 .\" X/Open Curses Issue 7 assumes some optimization will be done, but
 275 .\" does not mandate it in any way.
 276 .I optimizes
 277 its output by computing a minimal number of operations to mutate the
 278 screen from its state at the previous refresh to the new one.
 279 Effective optimization demands accurate information about the terminal
 280 device:
 281 the management of such information is the province of the
 282 \fB\%terminfo\fP(3X) API,
 283 a feature of every standard
 284 .I curses
 285 implementation.
 286 .PP
 287 Special windows called
 288 .I pads
 289 may also be manipulated.
 290 These are windows that are not constrained to the size of the terminal
 291 screen and whose contents need not be completely displayed.
 292 See \fB\%curs_pad\fP(3X).
 293 .PP
 294 In addition to drawing characters on the screen,
 295 rendering attributes and colors may be supported,
 296 causing the characters to show up in such modes as underlined,
 297 in reverse video,
 298 or in color on terminals that support such display enhancements.
 299 See \fB\%curs_attr\fP(3X).
 300 .PP
 301 .I curses
 302 predefines constants for a small set of forms-drawing graphics
 303 corresponding to the DEC Alternate Character Set (ACS),
 304 a feature of VT100 and other terminals.
 305 See \fB\%waddch\fP(3X).
 306 .PP
 307 .I curses
 308 is implemented using the operating system's terminal driver;
 309 keystroke events are received not as scan codes but as byte sequences.
 310 Graphical keycaps
 311 (alphanumeric and punctuation keys,
 312 and the space)
 313 appear as-is.
 314 Everything else,
 315 including the tab,
 316 enter/return,
 317 keypad,
 318 arrow,
 319 and function keys,
 320 appears as a control character or a multibyte
 321 .I "escape sequence."
 322 .I curses
 323 translates these into unique
 324 .I "key codes."
 325 See \fB\%getch\fP(3X).
 326 .PP
 327 .I \%ncurses
 328 provides reimplementations of the SVr4 \fBpanel\fP(3X), \fBform\fP(3X),
 329 and \fBmenu\fP(3X) libraries to ease construction of user interfaces
 330 with
 331 .IR curses .
 332 .SS "Initialization"
 333 The selection of an appropriate value of
 334 .I TERM
 335 in the process environment is essential to correct
 336 .I curses
 337 and
 338 .I \%term\%info
 339 library operation.
 340 A well-configured system selects a correct
 341 .I TERM
 342 value automatically;
 343 \fB\%tset\fP(1) may assist with troubleshooting exotic situations.
 344 .PP
 345 If you change the terminal type,
 346 export the
 347 .I TERM
 348 environment variable in the shell,
 349 then run \fB\%tset\fP(1) or the
 350 .RB \*(`` "@TPUT@ init" \*(''
 351 command.
 352 See subsection \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
 353 .PP
 354 If the environment variables
 355 .I \%LINES
 356 and
 357 .I \%COLUMNS
 358 are set,
 359 or if the
 360 .I curses
 361 program is executing in a graphical windowing environment,
 362 the information obtained thence overrides that obtained by
 363 .IR \%term\%info .
 364 An
 365 .I \%ncurses
 366 extension supports resizable terminals;
 367 see \fB\%wresize\fP(3X).
 368 .PP
 369 If the environment variable
 370 .I \%TERMINFO
 371 is defined,
 372 a
 373 .I curses
 374 program checks first for a terminal type description in the location it
 375 identifies.
 376 .I \%TERMINFO
 377 is useful for developing experimental type descriptions or when write
 378 permission to
 379 .I \%\*d
 380 is not available.
 381 .PP
 382 See section \*(``ENVIRONMENT\*('' below.
 383 .SS "Naming Conventions"
 384 .I curses
 385 offers many functions in variant forms using a regular set of
 386 alternatives to the name of an elemental one.
 387 Those prefixed with \*(``w\*('' require a
 388 .I \%WINDOW
 389 pointer argument;
 390 those with a \*(``mv\*('' prefix first perform cursor movement using
 391 \fB\%wmove\fP(3X);
 392 a \*(``mvw\*('' prefix indicates both.
 393 The \*(``w\*('' function is typically the elemental one;
 394 the removal of this prefix usually indicates operation on
 395 .BR \%stdscr .
 396 .PP
 397 Four functions prefixed with \*(``p\*('' require a pad argument.
 398 .PP
 399 In function synopses,
 400 .I \%ncurses
 401 man pages apply the following names to parameters.
 402 .PP
 403 .TS
 404 center;
 405 Li L.
 406 bf      \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
 407 win     pointer to a \fIWINDOW\fP
 408 pad     pointer to a \fIWINDOW\fP that is a pad
 409 .TE
 410 .SS "Wide and Non-wide Character Configurations"
 411 This manual page describes functions that appear in any configuration
 412 of the library.
 413 There are two common configurations;
 414 see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
 415 .TP 10 \" "ncursesw" + 2n
 416 .I \%ncurses
 417 is the library in its \*(``non-wide\*('' configuration,
 418 handling only eight-bit characters.
 419 It stores a character combined with attributes in a
 420 .I \%chtype
 421 datum,
 422 which is often an alias of
 423 .IR int .
 424 .IP
 425 Attributes alone
 426 (with no corresponding character)
 427 can be stored in variables of
 428 .I \%chtype
 429 or
 430 .I \%attr_t
 431 type.
 432 In either case,
 433 they are represented as an integral bit mask.
 434 .IP
 435 Each cell of a
 436 .I \%WINDOW
 437 is stored as a
 438 .IR \%chtype .
 439 .TP 10
 440 .I \%ncursesw
 441 is the library in its \*(``wide\*('' configuration,
 442 which handles character encodings requiring a larger data type than
 443 .I \%char
 444 (a byte-sized type)
 445 can represent.
 446 It adds about one third more calls using additional data types that
 447 can store such
 448 .I multibyte
 449 characters.
 450 .RS 10 \" same as foregoing tag width
 451 .TP 9 \" "cchar_t" + 2n
 452 .I \%cchar_t
 453 corresponds to the non-wide configuration's
 454 .IR \%chtype .
 455 It always a structure type,
 456 because it stores more data than fit into a standard scalar type.
 457 A character code may not be representable as a
 458 .IR \%char ,
 459 and moreover more than one character may occupy a cell
 460 (as with accent marks and other diacritics).
 461 Each character is of type
 462 .IR \%wchar_t ;
 463 a complex character contains one spacing character and zero or more
 464 non-spacing characters
 465 (see below).
 466 Attributes and color data are stored in separate fields of the
 467 structure,
 468 not combined as in
 469 .IR \%chtype .
 470 .PP
 471 Each cell of a
 472 .I \%WINDOW
 473 is stored as a
 474 .IR \%cchar_t .
 475 .PP
 476 \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
 477 store and retrieve
 478 .I \%cchar_t
 479 data.
 480 The wide library API of
 481 .I \%ncurses
 482 depends on two data types standardized by ISO C95.
 483 .TP 9
 484 .I \%wchar_t
 485 stores a wide character.
 486 Like
 487 .IR \%chtype ,
 488 it may be an alias of
 489 .IR int .
 490 Depending on the character encoding,
 491 a wide character may be
 492 .IR spacing ,
 493 meaning that it occupies a character cell by itself and typically
 494 accompanies cursor advancement,
 495 or
 496 .IR non-spacing ,
 497 meaning that it occupies the same cell as a spacing character,
 498 is often regarded as a \*(``modifier\*('' of the base glyph with which
 499 it combines,
 500 and typically does not advance the cursor.
 501 .TP 9
 502 .I \%wint_t
 503 can store a
 504 .I \%wchar_t
 505 or the constant
 506 .BR \%WEOF ,
 507 analogously to the
 508 .IR int -sized
 509 character manipulation functions of ISO C and its constant
 510 .BR \%EOF .
 511 .RE
 512 .IP
 513 The wide library provides additional functions that complement those in
 514 the non-wide library where the size of the underlying character type is
 515 significant.
 516 A somewhat regular naming convention relates many of the wide variants
 517 to their non-wide counterparts;
 518 where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
 519 prefix it with \*(``_w\*('' to obtain the wide counterpart.
 520 For example,
 521 \fB\%waddch\fP becomes \fB\%wadd_wch\fP.
 522 (Exceptions that add only \*(``w\*('' comprise
 523 .BR \%addwstr ,
 524 .BR \%inwstr ,
 525 and their variants.)
 526 .IP
 527 This convention is inapplicable to some non-wide function names,
 528 so other transformations are used for the wide configuration:
 529 the window background management function \*(``bkgd\*('' becomes
 530 \*(``bkgrnd\*('';
 531 the window border-drawing and -clearing functions are suffixed with
 532 \*(``_set\*('';
 533 and character attribute manipulation functions like
 534 \*(``attron\*('' become \*(``attr_on\*(''.
 535 .\"
 536 .SS "Function Name Index"
 537 The following table lists the
 538 .I curses
 539 functions provided in the non-wide and wide APIs and the corresponding
 540 man pages that describe them.
 541 Those flagged with \*(``*\*(''
 542 are
 543 .IR \%ncurses "-specific,"
 544 neither described by X/Open Curses nor present in SVr4.
 545 .PP
 546 .TS
 547 center tab(/);
 548 l l .
 549 \f(BIcurses\fP Function Name/Man Page
 550 _
 551 COLOR_PAIR/\fBcurs_color\fP(3X)
 552 PAIR_NUMBER/\fBcurs_color\fP(3X)
 553 add_wch/\fBcurs_add_wch\fP(3X)
 554 add_wchnstr/\fBcurs_add_wchstr\fP(3X)
 555 add_wchstr/\fBcurs_add_wchstr\fP(3X)
 556 addch/\fBcurs_addch\fP(3X)
 557 addchnstr/\fBcurs_addchstr\fP(3X)
 558 addchstr/\fBcurs_addchstr\fP(3X)
 559 addnstr/\fBcurs_addstr\fP(3X)
 560 addnwstr/\fBcurs_addwstr\fP(3X)
 561 addstr/\fBcurs_addstr\fP(3X)
 562 addwstr/\fBcurs_addwstr\fP(3X)
 563 alloc_pair/\fBnew_pair\fP(3X)*
 564 assume_default_colors/\fBdefault_colors\fP(3X)*
 565 attr_get/\fBcurs_attr\fP(3X)
 566 attr_off/\fBcurs_attr\fP(3X)
 567 attr_on/\fBcurs_attr\fP(3X)
 568 attr_set/\fBcurs_attr\fP(3X)
 569 attroff/\fBcurs_attr\fP(3X)
 570 attron/\fBcurs_attr\fP(3X)
 571 attrset/\fBcurs_attr\fP(3X)
 572 baudrate/\fBcurs_termattrs\fP(3X)
 573 beep/\fBcurs_beep\fP(3X)
 574 bkgd/\fBcurs_bkgd\fP(3X)
 575 bkgdset/\fBcurs_bkgd\fP(3X)
 576 bkgrnd/\fBcurs_bkgrnd\fP(3X)
 577 bkgrndset/\fBcurs_bkgrnd\fP(3X)
 578 border/\fBcurs_border\fP(3X)
 579 border_set/\fBcurs_border_set\fP(3X)
 580 box/\fBcurs_border\fP(3X)
 581 box_set/\fBcurs_border_set\fP(3X)
 582 can_change_color/\fBcurs_color\fP(3X)
 583 cbreak/\fBcurs_inopts\fP(3X)
 584 chgat/\fBcurs_attr\fP(3X)
 585 clear/\fBcurs_clear\fP(3X)
 586 clearok/\fBcurs_outopts\fP(3X)
 587 clrtobot/\fBcurs_clear\fP(3X)
 588 clrtoeol/\fBcurs_clear\fP(3X)
 589 color_content/\fBcurs_color\fP(3X)
 590 color_set/\fBcurs_attr\fP(3X)
 591 copywin/\fBcurs_overlay\fP(3X)
 592 curs_set/\fBcurs_kernel\fP(3X)
 593 curses_trace/\fBcurs_trace\fP(3X)*
 594 curses_version/\fBcurs_extend\fP(3X)*
 595 def_prog_mode/\fBcurs_kernel\fP(3X)
 596 def_shell_mode/\fBcurs_kernel\fP(3X)
 597 define_key/\fBdefine_key\fP(3X)*
 598 del_curterm/\fBcurs_terminfo\fP(3X)
 599 delay_output/\fBcurs_util\fP(3X)
 600 delch/\fBcurs_delch\fP(3X)
 601 deleteln/\fBcurs_deleteln\fP(3X)
 602 delscreen/\fBcurs_initscr\fP(3X)
 603 delwin/\fBcurs_window\fP(3X)
 604 derwin/\fBcurs_window\fP(3X)
 605 doupdate/\fBcurs_refresh\fP(3X)
 606 dupwin/\fBcurs_window\fP(3X)
 607 echo/\fBcurs_inopts\fP(3X)
 608 echo_wchar/\fBcurs_add_wch\fP(3X)
 609 echochar/\fBcurs_addch\fP(3X)
 610 endwin/\fBcurs_initscr\fP(3X)
 611 erase/\fBcurs_clear\fP(3X)
 612 erasechar/\fBcurs_termattrs\fP(3X)
 613 erasewchar/\fBcurs_termattrs\fP(3X)
 614 exit_curses/\fBcurs_memleaks\fP(3X)*
 615 exit_terminfo/\fBcurs_memleaks\fP(3X)*
 616 extended_color_content/\fBcurs_color\fP(3X)*
 617 extended_pair_content/\fBcurs_color\fP(3X)*
 618 extended_slk_color/\fBcurs_slk\fP(3X)*
 619 filter/\fBcurs_util\fP(3X)
 620 find_pair/\fBnew_pair\fP(3X)*
 621 flash/\fBcurs_beep\fP(3X)
 622 flushinp/\fBcurs_util\fP(3X)
 623 free_pair/\fBnew_pair\fP(3X)*
 624 get_escdelay/\fBcurs_threads\fP(3X)*
 625 get_wch/\fBcurs_get_wch\fP(3X)
 626 get_wstr/\fBcurs_get_wstr\fP(3X)
 627 getattrs/\fBcurs_attr\fP(3X)
 628 getbegx/\fBcurs_legacy\fP(3X)*
 629 getbegy/\fBcurs_legacy\fP(3X)*
 630 getbegyx/\fBcurs_getyx\fP(3X)
 631 getbkgd/\fBcurs_bkgd\fP(3X)
 632 getbkgrnd/\fBcurs_bkgrnd\fP(3X)
 633 getcchar/\fBcurs_getcchar\fP(3X)
 634 getch/\fBcurs_getch\fP(3X)
 635 getcurx/\fBcurs_legacy\fP(3X)*
 636 getcury/\fBcurs_legacy\fP(3X)*
 637 getmaxx/\fBcurs_legacy\fP(3X)*
 638 getmaxy/\fBcurs_legacy\fP(3X)*
 639 getmaxyx/\fBcurs_getyx\fP(3X)
 640 getmouse/\fBcurs_mouse\fP(3X)*
 641 getn_wstr/\fBcurs_get_wstr\fP(3X)
 642 getnstr/\fBcurs_getstr\fP(3X)
 643 getparx/\fBcurs_legacy\fP(3X)*
 644 getpary/\fBcurs_legacy\fP(3X)*
 645 getparyx/\fBcurs_getyx\fP(3X)
 646 getstr/\fBcurs_getstr\fP(3X)
 647 getsyx/\fBcurs_kernel\fP(3X)
 648 getwin/\fBcurs_util\fP(3X)
 649 getyx/\fBcurs_getyx\fP(3X)
 650 halfdelay/\fBcurs_inopts\fP(3X)
 651 has_colors/\fBcurs_color\fP(3X)
 652 has_ic/\fBcurs_termattrs\fP(3X)
 653 has_il/\fBcurs_termattrs\fP(3X)
 654 has_key/\fBcurs_getch\fP(3X)*
 655 has_mouse/\fBcurs_mouse\fP(3X)*
 656 hline/\fBcurs_border\fP(3X)
 657 hline_set/\fBcurs_border_set\fP(3X)
 658 idcok/\fBcurs_outopts\fP(3X)
 659 idlok/\fBcurs_outopts\fP(3X)
 660 immedok/\fBcurs_outopts\fP(3X)
 661 in_wch/\fBcurs_in_wch\fP(3X)
 662 in_wchnstr/\fBcurs_in_wchstr\fP(3X)
 663 in_wchstr/\fBcurs_in_wchstr\fP(3X)
 664 inch/\fBcurs_inch\fP(3X)
 665 inchnstr/\fBcurs_inchstr\fP(3X)
 666 inchstr/\fBcurs_inchstr\fP(3X)
 667 init_color/\fBcurs_color\fP(3X)
 668 init_extended_color/\fBcurs_color\fP(3X)*
 669 init_extended_pair/\fBcurs_color\fP(3X)*
 670 init_pair/\fBcurs_color\fP(3X)
 671 initscr/\fBcurs_initscr\fP(3X)
 672 innstr/\fBcurs_instr\fP(3X)
 673 innwstr/\fBcurs_inwstr\fP(3X)
 674 ins_nwstr/\fBcurs_ins_wstr\fP(3X)
 675 ins_wch/\fBcurs_ins_wch\fP(3X)
 676 ins_wstr/\fBcurs_ins_wstr\fP(3X)
 677 insch/\fBcurs_insch\fP(3X)
 678 insdelln/\fBcurs_deleteln\fP(3X)
 679 insertln/\fBcurs_deleteln\fP(3X)
 680 insnstr/\fBcurs_insstr\fP(3X)
 681 insstr/\fBcurs_insstr\fP(3X)
 682 instr/\fBcurs_instr\fP(3X)
 683 intrflush/\fBcurs_inopts\fP(3X)
 684 inwstr/\fBcurs_inwstr\fP(3X)
 685 is_cbreak/\fBcurs_inopts\fP(3X)*
 686 is_cleared/\fBcurs_opaque\fP(3X)*
 687 is_echo/\fBcurs_inopts\fP(3X)*
 688 is_idcok/\fBcurs_opaque\fP(3X)*
 689 is_idlok/\fBcurs_opaque\fP(3X)*
 690 is_immedok/\fBcurs_opaque\fP(3X)*
 691 is_keypad/\fBcurs_opaque\fP(3X)*
 692 is_leaveok/\fBcurs_opaque\fP(3X)*
 693 is_linetouched/\fBcurs_touch\fP(3X)
 694 is_nl/\fBcurs_inopts\fP(3X)*
 695 is_nodelay/\fBcurs_opaque\fP(3X)*
 696 is_notimeout/\fBcurs_opaque\fP(3X)*
 697 is_pad/\fBcurs_opaque\fP(3X)*
 698 is_raw/\fBcurs_inopts\fP(3X)*
 699 is_scrollok/\fBcurs_opaque\fP(3X)*
 700 is_subwin/\fBcurs_opaque\fP(3X)*
 701 is_syncok/\fBcurs_opaque\fP(3X)*
 702 is_term_resized/\fBresizeterm\fP(3X)*
 703 is_wintouched/\fBcurs_touch\fP(3X)
 704 isendwin/\fBcurs_initscr\fP(3X)
 705 key_defined/\fBkey_defined\fP(3X)*
 706 key_name/\fBcurs_util\fP(3X)
 707 keybound/\fBkeybound\fP(3X)*
 708 keyname/\fBcurs_util\fP(3X)
 709 keyok/\fBkeyok\fP(3X)*
 710 keypad/\fBcurs_inopts\fP(3X)
 711 killchar/\fBcurs_termattrs\fP(3X)
 712 killwchar/\fBcurs_termattrs\fP(3X)
 713 leaveok/\fBcurs_outopts\fP(3X)
 714 longname/\fBcurs_termattrs\fP(3X)
 715 mcprint/\fBcurs_print\fP(3X)*
 716 meta/\fBcurs_inopts\fP(3X)
 717 mouse_trafo/\fBcurs_mouse\fP(3X)*
 718 mouseinterval/\fBcurs_mouse\fP(3X)*
 719 mousemask/\fBcurs_mouse\fP(3X)*
 720 move/\fBcurs_move\fP(3X)
 721 mvadd_wch/\fBcurs_add_wch\fP(3X)
 722 mvadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
 723 mvadd_wchstr/\fBcurs_add_wchstr\fP(3X)
 724 mvaddch/\fBcurs_addch\fP(3X)
 725 mvaddchnstr/\fBcurs_addchstr\fP(3X)
 726 mvaddchstr/\fBcurs_addchstr\fP(3X)
 727 mvaddnstr/\fBcurs_addstr\fP(3X)
 728 mvaddnwstr/\fBcurs_addwstr\fP(3X)
 729 mvaddstr/\fBcurs_addstr\fP(3X)
 730 mvaddwstr/\fBcurs_addwstr\fP(3X)
 731 mvchgat/\fBcurs_attr\fP(3X)
 732 mvcur/\fBcurs_terminfo\fP(3X)
 733 mvdelch/\fBcurs_delch\fP(3X)
 734 mvderwin/\fBcurs_window\fP(3X)
 735 mvget_wch/\fBcurs_get_wch\fP(3X)
 736 mvget_wstr/\fBcurs_get_wstr\fP(3X)
 737 mvgetch/\fBcurs_getch\fP(3X)
 738 mvgetn_wstr/\fBcurs_get_wstr\fP(3X)
 739 mvgetnstr/\fBcurs_getstr\fP(3X)
 740 mvgetstr/\fBcurs_getstr\fP(3X)
 741 mvhline/\fBcurs_border\fP(3X)
 742 mvhline_set/\fBcurs_border_set\fP(3X)
 743 mvin_wch/\fBcurs_in_wch\fP(3X)
 744 mvin_wchnstr/\fBcurs_in_wchstr\fP(3X)
 745 mvin_wchstr/\fBcurs_in_wchstr\fP(3X)
 746 mvinch/\fBcurs_inch\fP(3X)
 747 mvinchnstr/\fBcurs_inchstr\fP(3X)
 748 mvinchstr/\fBcurs_inchstr\fP(3X)
 749 mvinnstr/\fBcurs_instr\fP(3X)
 750 mvinnwstr/\fBcurs_inwstr\fP(3X)
 751 mvins_nwstr/\fBcurs_ins_wstr\fP(3X)
 752 mvins_wch/\fBcurs_ins_wch\fP(3X)
 753 mvins_wstr/\fBcurs_ins_wstr\fP(3X)
 754 mvinsch/\fBcurs_insch\fP(3X)
 755 mvinsnstr/\fBcurs_insstr\fP(3X)
 756 mvinsstr/\fBcurs_insstr\fP(3X)
 757 mvinstr/\fBcurs_instr\fP(3X)
 758 mvinwstr/\fBcurs_inwstr\fP(3X)
 759 mvprintw/\fBcurs_printw\fP(3X)
 760 mvscanw/\fBcurs_scanw\fP(3X)
 761 mvvline/\fBcurs_border\fP(3X)
 762 mvvline_set/\fBcurs_border_set\fP(3X)
 763 mvwadd_wch/\fBcurs_add_wch\fP(3X)
 764 mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
 765 mvwadd_wchstr/\fBcurs_add_wchstr\fP(3X)
 766 mvwaddch/\fBcurs_addch\fP(3X)
 767 mvwaddchnstr/\fBcurs_addchstr\fP(3X)
 768 mvwaddchstr/\fBcurs_addchstr\fP(3X)
 769 mvwaddnstr/\fBcurs_addstr\fP(3X)
 770 mvwaddnwstr/\fBcurs_addwstr\fP(3X)
 771 mvwaddstr/\fBcurs_addstr\fP(3X)
 772 mvwaddwstr/\fBcurs_addwstr\fP(3X)
 773 mvwchgat/\fBcurs_attr\fP(3X)
 774 mvwdelch/\fBcurs_delch\fP(3X)
 775 mvwget_wch/\fBcurs_get_wch\fP(3X)
 776 mvwget_wstr/\fBcurs_get_wstr\fP(3X)
 777 mvwgetch/\fBcurs_getch\fP(3X)
 778 mvwgetn_wstr/\fBcurs_get_wstr\fP(3X)
 779 mvwgetnstr/\fBcurs_getstr\fP(3X)
 780 mvwgetstr/\fBcurs_getstr\fP(3X)
 781 mvwhline/\fBcurs_border\fP(3X)
 782 mvwhline_set/\fBcurs_border_set\fP(3X)
 783 mvwin/\fBcurs_window\fP(3X)
 784 mvwin_wch/\fBcurs_in_wch\fP(3X)
 785 mvwin_wchnstr/\fBcurs_in_wchstr\fP(3X)
 786 mvwin_wchstr/\fBcurs_in_wchstr\fP(3X)
 787 mvwinch/\fBcurs_inch\fP(3X)
 788 mvwinchnstr/\fBcurs_inchstr\fP(3X)
 789 mvwinchstr/\fBcurs_inchstr\fP(3X)
 790 mvwinnstr/\fBcurs_instr\fP(3X)
 791 mvwinnwstr/\fBcurs_inwstr\fP(3X)
 792 mvwins_nwstr/\fBcurs_ins_wstr\fP(3X)
 793 mvwins_wch/\fBcurs_ins_wch\fP(3X)
 794 mvwins_wstr/\fBcurs_ins_wstr\fP(3X)
 795 mvwinsch/\fBcurs_insch\fP(3X)
 796 mvwinsnstr/\fBcurs_insstr\fP(3X)
 797 mvwinsstr/\fBcurs_insstr\fP(3X)
 798 mvwinstr/\fBcurs_instr\fP(3X)
 799 mvwinwstr/\fBcurs_inwstr\fP(3X)
 800 mvwprintw/\fBcurs_printw\fP(3X)
 801 mvwscanw/\fBcurs_scanw\fP(3X)
 802 mvwvline/\fBcurs_border\fP(3X)
 803 mvwvline_set/\fBcurs_border_set\fP(3X)
 804 napms/\fBcurs_kernel\fP(3X)
 805 newpad/\fBcurs_pad\fP(3X)
 806 newterm/\fBcurs_initscr\fP(3X)
 807 newwin/\fBcurs_window\fP(3X)
 808 nl/\fBcurs_inopts\fP(3X)
 809 nocbreak/\fBcurs_inopts\fP(3X)
 810 nodelay/\fBcurs_inopts\fP(3X)
 811 noecho/\fBcurs_inopts\fP(3X)
 812 nofilter/\fBcurs_util\fP(3X)*
 813 nonl/\fBcurs_inopts\fP(3X)
 814 noqiflush/\fBcurs_inopts\fP(3X)
 815 noraw/\fBcurs_inopts\fP(3X)
 816 notimeout/\fBcurs_inopts\fP(3X)
 817 overlay/\fBcurs_overlay\fP(3X)
 818 overwrite/\fBcurs_overlay\fP(3X)
 819 pair_content/\fBcurs_color\fP(3X)
 820 pecho_wchar/\fBcurs_pad\fP(3X)
 821 pechochar/\fBcurs_pad\fP(3X)
 822 pnoutrefresh/\fBcurs_pad\fP(3X)
 823 prefresh/\fBcurs_pad\fP(3X)
 824 printw/\fBcurs_printw\fP(3X)
 825 putp/\fBcurs_terminfo\fP(3X)
 826 putwin/\fBcurs_util\fP(3X)
 827 qiflush/\fBcurs_inopts\fP(3X)
 828 raw/\fBcurs_inopts\fP(3X)
 829 redrawwin/\fBcurs_refresh\fP(3X)
 830 refresh/\fBcurs_refresh\fP(3X)
 831 reset_color_pairs/\fBcurs_color\fP(3X)*
 832 reset_prog_mode/\fBcurs_kernel\fP(3X)
 833 reset_shell_mode/\fBcurs_kernel\fP(3X)
 834 resetty/\fBcurs_kernel\fP(3X)
 835 resize_term/\fBresizeterm\fP(3X)*
 836 resizeterm/\fBresizeterm\fP(3X)*
 837 restartterm/\fBcurs_terminfo\fP(3X)
 838 ripoffline/\fBcurs_kernel\fP(3X)
 839 savetty/\fBcurs_kernel\fP(3X)
 840 scanw/\fBcurs_scanw\fP(3X)
 841 scr_dump/\fBcurs_scr_dump\fP(3X)
 842 scr_init/\fBcurs_scr_dump\fP(3X)
 843 scr_restore/\fBcurs_scr_dump\fP(3X)
 844 scr_set/\fBcurs_scr_dump\fP(3X)
 845 scrl/\fBcurs_scroll\fP(3X)
 846 scroll/\fBcurs_scroll\fP(3X)
 847 scrollok/\fBcurs_outopts\fP(3X)
 848 set_curterm/\fBcurs_terminfo\fP(3X)
 849 set_escdelay/\fBcurs_threads\fP(3X)*
 850 set_tabsize/\fBcurs_threads\fP(3X)*
 851 set_term/\fBcurs_initscr\fP(3X)
 852 setcchar/\fBcurs_getcchar\fP(3X)
 853 setscrreg/\fBcurs_outopts\fP(3X)
 854 setsyx/\fBcurs_kernel\fP(3X)
 855 setupterm/\fBcurs_terminfo\fP(3X)
 856 slk_attr/\fBcurs_slk\fP(3X)*
 857 slk_attr_off/\fBcurs_slk\fP(3X)
 858 slk_attr_on/\fBcurs_slk\fP(3X)
 859 slk_attr_set/\fBcurs_slk\fP(3X)
 860 slk_attroff/\fBcurs_slk\fP(3X)
 861 slk_attron/\fBcurs_slk\fP(3X)
 862 slk_attrset/\fBcurs_slk\fP(3X)
 863 slk_clear/\fBcurs_slk\fP(3X)
 864 slk_color/\fBcurs_slk\fP(3X)
 865 slk_init/\fBcurs_slk\fP(3X)
 866 slk_label/\fBcurs_slk\fP(3X)
 867 slk_noutrefresh/\fBcurs_slk\fP(3X)
 868 slk_refresh/\fBcurs_slk\fP(3X)
 869 slk_restore/\fBcurs_slk\fP(3X)
 870 slk_set/\fBcurs_slk\fP(3X)
 871 slk_touch/\fBcurs_slk\fP(3X)
 872 slk_wset/\fBcurs_slk\fP(3X)
 873 standend/\fBcurs_attr\fP(3X)
 874 standout/\fBcurs_attr\fP(3X)
 875 start_color/\fBcurs_color\fP(3X)
 876 subpad/\fBcurs_pad\fP(3X)
 877 subwin/\fBcurs_window\fP(3X)
 878 syncok/\fBcurs_window\fP(3X)
 879 term_attrs/\fBcurs_termattrs\fP(3X)
 880 termattrs/\fBcurs_termattrs\fP(3X)
 881 termname/\fBcurs_termattrs\fP(3X)
 882 tgetent/\fBcurs_termcap\fP(3X)
 883 tgetflag/\fBcurs_termcap\fP(3X)
 884 tgetnum/\fBcurs_termcap\fP(3X)
 885 tgetstr/\fBcurs_termcap\fP(3X)
 886 tgoto/\fBcurs_termcap\fP(3X)
 887 tigetflag/\fBcurs_terminfo\fP(3X)
 888 tigetnum/\fBcurs_terminfo\fP(3X)
 889 tigetstr/\fBcurs_terminfo\fP(3X)
 890 timeout/\fBcurs_inopts\fP(3X)
 891 tiparm/\fBcurs_terminfo\fP(3X)
 892 tiparm_s/\fBcurs_terminfo\fP(3X)*
 893 tiscan_s/\fBcurs_terminfo\fP(3X)*
 894 touchline/\fBcurs_touch\fP(3X)
 895 touchwin/\fBcurs_touch\fP(3X)
 896 tparm/\fBcurs_terminfo\fP(3X)
 897 tputs/\fBcurs_termcap\fP(3X)
 898 tputs/\fBcurs_terminfo\fP(3X)
 899 trace/\fBcurs_trace\fP(3X)*
 900 typeahead/\fBcurs_inopts\fP(3X)
 901 unctrl/\fBcurs_util\fP(3X)
 902 unget_wch/\fBcurs_get_wch\fP(3X)
 903 ungetch/\fBcurs_getch\fP(3X)
 904 ungetmouse/\fBcurs_mouse\fP(3X)*
 905 untouchwin/\fBcurs_touch\fP(3X)
 906 use_default_colors/\fBdefault_colors\fP(3X)*
 907 use_env/\fBcurs_util\fP(3X)
 908 use_extended_names/\fBcurs_extend\fP(3X)*
 909 use_legacy_coding/\fBlegacy_coding\fP(3X)*
 910 use_screen/\fBcurs_threads\fP(3X)*
 911 use_tioctl/\fBcurs_util\fP(3X)*
 912 use_window/\fBcurs_threads\fP(3X)*
 913 vid_attr/\fBcurs_terminfo\fP(3X)
 914 vid_puts/\fBcurs_terminfo\fP(3X)
 915 vidattr/\fBcurs_terminfo\fP(3X)
 916 vidputs/\fBcurs_terminfo\fP(3X)
 917 vline/\fBcurs_border\fP(3X)
 918 vline_set/\fBcurs_border_set\fP(3X)
 919 vw_printw/\fBcurs_printw\fP(3X)
 920 vw_scanw/\fBcurs_scanw\fP(3X)
 921 vwprintw/\fBcurs_printw\fP(3X)
 922 vwscanw/\fBcurs_scanw\fP(3X)
 923 wadd_wch/\fBcurs_add_wch\fP(3X)
 924 wadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
 925 wadd_wchstr/\fBcurs_add_wchstr\fP(3X)
 926 waddch/\fBcurs_addch\fP(3X)
 927 waddchnstr/\fBcurs_addchstr\fP(3X)
 928 waddchstr/\fBcurs_addchstr\fP(3X)
 929 waddnstr/\fBcurs_addstr\fP(3X)
 930 waddnwstr/\fBcurs_addwstr\fP(3X)
 931 waddstr/\fBcurs_addstr\fP(3X)
 932 waddwstr/\fBcurs_addwstr\fP(3X)
 933 wattr_get/\fBcurs_attr\fP(3X)
 934 wattr_off/\fBcurs_attr\fP(3X)
 935 wattr_on/\fBcurs_attr\fP(3X)
 936 wattr_set/\fBcurs_attr\fP(3X)
 937 wattroff/\fBcurs_attr\fP(3X)
 938 wattron/\fBcurs_attr\fP(3X)
 939 wattrset/\fBcurs_attr\fP(3X)
 940 wbkgd/\fBcurs_bkgd\fP(3X)
 941 wbkgdset/\fBcurs_bkgd\fP(3X)
 942 wbkgrnd/\fBcurs_bkgrnd\fP(3X)
 943 wbkgrndset/\fBcurs_bkgrnd\fP(3X)
 944 wborder/\fBcurs_border\fP(3X)
 945 wborder_set/\fBcurs_border_set\fP(3X)
 946 wchgat/\fBcurs_attr\fP(3X)
 947 wclear/\fBcurs_clear\fP(3X)
 948 wclrtobot/\fBcurs_clear\fP(3X)
 949 wclrtoeol/\fBcurs_clear\fP(3X)
 950 wcolor_set/\fBcurs_attr\fP(3X)
 951 wcursyncup/\fBcurs_window\fP(3X)
 952 wdelch/\fBcurs_delch\fP(3X)
 953 wdeleteln/\fBcurs_deleteln\fP(3X)
 954 wecho_wchar/\fBcurs_add_wch\fP(3X)
 955 wechochar/\fBcurs_addch\fP(3X)
 956 wenclose/\fBcurs_mouse\fP(3X)*
 957 werase/\fBcurs_clear\fP(3X)
 958 wget_wch/\fBcurs_get_wch\fP(3X)
 959 wget_wstr/\fBcurs_get_wstr\fP(3X)
 960 wgetbkgrnd/\fBcurs_bkgrnd\fP(3X)
 961 wgetch/\fBcurs_getch\fP(3X)
 962 wgetdelay/\fBcurs_opaque\fP(3X)*
 963 wgetn_wstr/\fBcurs_get_wstr\fP(3X)
 964 wgetnstr/\fBcurs_getstr\fP(3X)
 965 wgetparent/\fBcurs_opaque\fP(3X)*
 966 wgetscrreg/\fBcurs_opaque\fP(3X)*
 967 wgetstr/\fBcurs_getstr\fP(3X)
 968 whline/\fBcurs_border\fP(3X)
 969 whline_set/\fBcurs_border_set\fP(3X)
 970 win_wch/\fBcurs_in_wch\fP(3X)
 971 win_wchnstr/\fBcurs_in_wchstr\fP(3X)
 972 win_wchstr/\fBcurs_in_wchstr\fP(3X)
 973 winch/\fBcurs_inch\fP(3X)
 974 winchnstr/\fBcurs_inchstr\fP(3X)
 975 winchstr/\fBcurs_inchstr\fP(3X)
 976 winnstr/\fBcurs_instr\fP(3X)
 977 winnwstr/\fBcurs_inwstr\fP(3X)
 978 wins_nwstr/\fBcurs_ins_wstr\fP(3X)
 979 wins_wch/\fBcurs_ins_wch\fP(3X)
 980 wins_wstr/\fBcurs_ins_wstr\fP(3X)
 981 winsch/\fBcurs_insch\fP(3X)
 982 winsdelln/\fBcurs_deleteln\fP(3X)
 983 winsertln/\fBcurs_deleteln\fP(3X)
 984 winsnstr/\fBcurs_insstr\fP(3X)
 985 winsstr/\fBcurs_insstr\fP(3X)
 986 winstr/\fBcurs_instr\fP(3X)
 987 winwstr/\fBcurs_inwstr\fP(3X)
 988 wmouse_trafo/\fBcurs_mouse\fP(3X)*
 989 wmove/\fBcurs_move\fP(3X)
 990 wnoutrefresh/\fBcurs_refresh\fP(3X)
 991 wprintw/\fBcurs_printw\fP(3X)
 992 wredrawln/\fBcurs_refresh\fP(3X)
 993 wrefresh/\fBcurs_refresh\fP(3X)
 994 wresize/\fBwresize\fP(3X)*
 995 wscanw/\fBcurs_scanw\fP(3X)
 996 wscrl/\fBcurs_scroll\fP(3X)
 997 wsetscrreg/\fBcurs_outopts\fP(3X)
 998 wstandend/\fBcurs_attr\fP(3X)
 999 wstandout/\fBcurs_attr\fP(3X)
1000 wsyncdown/\fBcurs_window\fP(3X)
1001 wsyncup/\fBcurs_window\fP(3X)
1002 wtimeout/\fBcurs_inopts\fP(3X)
1003 wtouchln/\fBcurs_touch\fP(3X)
1004 wunctrl/\fBcurs_util\fP(3X)
1005 wvline/\fBcurs_border\fP(3X)
1006 wvline_set/\fBcurs_border_set\fP(3X)
1007 .TE
1008 .PP
1009 .IR \%ncurses 's
1010 .I "screen-pointer extension"
1011 adds additional functions corresponding to many of the above,
1012 each with an \*(``_sp\*('' suffix;
1013 see \fBcurs_sp_funcs\fP(3X).
1014 .PP
1015 The availability of some extensions is configurable when
1016 .I \%ncurses
1017 is compiled;
1018 see sections \*(``ALTERNATE CONFIGURATIONS\*('' and \*(``EXTENSIONS\*(''
1019 below.
1020 .SH RETURN VALUE
1021 Unless otherwise noted,
1022 functions that return an integer return
1023 .B OK
1024 on success and
1025 .B ERR
1026 on failure.
1027 Functions that return pointers return
1028 .B NULL
1029 on failure.
1030 Typically,
1031 .I \%ncurses
1032 treats a null pointer passed as a function parameter as a failure.
1033 Functions with a \*(``mv\*('' prefix first perform cursor movement using
1034 \fB\%wmove\fP(3X) and fail if the position is outside the window.
1035 .SH ENVIRONMENT
1036 The following symbols from the process environment customize the
1037 runtime behavior of
1038 .I \%ncurses
1039 applications.
1040 The library may be configured to disregard the variables
1041 .IR \%TERMINFO ,
1042 .IR \%TERMINFO_DIRS ,
1043 .IR \%TERMPATH ,
1044 and
1045 .IR HOME ,
1046 if the user is the superuser (root),
1047 or the application uses \fI\%setuid\fP(2) or \fI\%setgid\fP(2).
1048 .SS "\fIBAUDRATE\fP"
1049 The debugging library checks this variable when the application has
1050 redirected output to a file.
1051 Its integral value is used for the baud rate.
1052 If that value is absent or invalid,
1053 .I \%ncurses
1054 uses 9600.
1055 This feature allows testers to construct repeatable test cases
1056 that take into account optimization decisions that depend on baud rate.
1057 .SS "\fICC\fP (command character)"
1058 When set,
1059 the
1060 .B \%command_character
1061 .RB ( \%cmdch )
1062 capability value of loaded
1063 .I \%term\%info
1064 entries changes to the value of this variable.
1065 Very few
1066 .I \%term\%info
1067 entries provide this feature.
1068 .PP
1069 Because this name is also used in development environments to represent
1070 the C compiler's name,
1071 .I \%ncurses
1072 ignores its value if it is not one character in length.
1073 .SS "\fICOLUMNS\fP"
1074 This variable specifies the width of the screen in characters.
1075 Applications running in a windowing environment usually are able to
1076 obtain the width of the window in which they are executing.
1077 If
1078 .I \%COLUMNS
1079 is not defined and the terminal's screen size is not available from the
1080 terminal driver,
1081 .I \%ncurses
1082 uses the size specified by the
1083 .B \%columns
1084 .RB ( \%cols )
1085 capability of the terminal type's entry in the
1086 .I \%term\%info
1087 database,
1088 if any.
1089 .PP
1090 It is important that your application use the correct screen size.
1091 Automatic detection thereof is not always possible because an
1092 application may be running on a host that does not honor NAWS
1093 (Negotiations About Window Size)
1094 or as a different user ID than the owner of the terminal device file.
1095 Setting
1096 .I \%COLUMNS
1097 and/or
1098 .I \%LINES
1099 overrides the library's use of the screen size obtained from the
1100 operating system.
1101 .PP
1102 The
1103 .I \%COLUMNS
1104 and
1105 .I \%LINES
1106 variables may be specified independently.
1107 This property is useful to circumvent misfeatures of legacy terminal
1108 type descriptions;
1109 \fI\%xterm\fP(1) descriptions specifying 65 lines were once notorious.
1110 For best results,
1111 avoid specifying
1112 .B cols
1113 and
1114 .B lines
1115 capability codes in
1116 .I \%term\%info
1117 descriptions of terminal emulators.
1118 .PP
1119 \fBuse_env\fP(3X) can disable use of the process environment
1120 in determining the screen size.
1121 \fBuse_tioctl\fP(3X) can update
1122 .I \%COLUMNS
1123 and
1124 .I \%LINES
1125 to match the screen size obtained from system calls or the terminal
1126 database.
1127 .SS "\fIESCDELAY\fP"
1128 For
1129 .I curses
1130 to distinguish the ESC character resulting from a user's press of the
1131 \*(``Escape\*('' key on the input device from one beginning an
1132 .I "escape sequence"
1133 (as commonly produced by function keys),
1134 it waits after receiving the escape character to see if further
1135 characters are available on the input stream within a short interval.
1136 A global variable
1137 .B \%ESCDELAY
1138 stores this interval in milliseconds.
1139 The default value of 1000
1140 (one second)
1141 is adequate for most uses.
1142 This environment variable overrides it.
1143 .PP
1144 The most common instance where you may wish to change this value
1145 is to work with a remote host over a slow communication channel.
1146 If the host running a
1147 .I curses
1148 application does not receive the characters of an escape sequence in a
1149 timely manner,
1150 the library can interpret them as multiple key stroke events.
1151 .PP
1152 \fI\%xterm\fP(1) mouse events are a form of escape sequence;
1153 therefore,
1154 if your application makes heavy use of multiple-clicking,
1155 you may wish to lengthen the default value because the delay applies
1156 to the composite multi-click event as well as the individual clicks.
1157 .PP
1158 Portable applications should not rely upon the presence of
1159 .B \%ESCDELAY
1160 in either form,
1161 but setting the environment variable rather than the global variable
1162 does not create problems when compiling an application.
1163 .PP
1164 If \fB\%keypad\fP(3X) is disabled for the
1165 .I curses
1166 window receiving input,
1167 a program must disambiguate escape sequences itself.
1168 .SS "\fIHOME\fP"
1169 .I \%ncurses
1170 may read and write auxiliary terminal descriptions in
1171 .I \%.termcap
1172 and
1173 .I \%.terminfo
1174 files in the user's home directory.
1175 .SS "\fILINES\fP"
1176 This counterpart to
1177 .I \%COLUMNS
1178 specifies the height of the screen in characters.
1179 The corresponding
1180 .I \%term\%info
1181 capability and code is
1182 .BR \%lines .
1183 See the description of the
1184 .I \%COLUMNS
1185 variable above.
1186 .SS "\fIMOUSE_BUTTONS_123\fP"
1187 (OS/2 EMX port only)
1188 OS/2 numbers a three-button mouse inconsistently with other platforms,
1189 such that 1 is the left button,
1190 2 the right,
1191 and 3 the middle.
1192 This variable customizes the mouse button numbering.
1193 Its value must be three digits 1\-3 in any order.
1194 By default,
1195 .I \%ncurses
1196 assumes a numbering of \*(``132\*(''.
1197 .SS "\fINCURSES_ASSUMED_COLORS\fP"
1198 If set,
1199 this variable overrides the
1200 .I \%ncurses
1201 library's compiled-in assumption that the terminal's default colors are
1202 white on black;
1203 see \fB\%default_colors\fP(3X).
1204 Set the foreground and background color values with this environment
1205 variable by assigning it two integer values separated by a comma,
1206 indicating foregound and background color numbers,
1207 respectively.
1208 .PP
1209 For example,
1210 to tell
1211 .I \%ncurses
1212 not to assume anything about the colors,
1213 use a value of \*(``\-1,\-1\*(''.
1214 To make the default color scheme green on black,
1215 use \*(``2,0\*(''.
1216 .I \%ncurses
1217 accepts integral values from \-1 up to the value of the
1218 .I \%term\%info
1219 .B \%max_colors
1220 .RB ( colors )
1221 capability.
1222 .SS "\fINCURSES_CONSOLE2\fP"
1223 (MinGW port only)
1224 The
1225 .I \%Console2
1226 .\" https://www.hanselman.com/blog/console2-a-better-windows-command-prompt
1227 program defectively handles the Microsoft Console API call
1228 .IR \%Create\%Console\%Screen\%Buffer .
1229 Applications that use it will hang.
1230 However,
1231 it is possible to simulate the action of this call by mapping
1232 coordinates,
1233 explicitly saving and restoring the original screen contents.
1234 Setting the environment variable
1235 .I \%NCGDB
1236 has the same effect.
1237 .SS "\fINCURSES_GPM_TERMS\fP"
1238 (Linux only)
1239 When
1240 .I \%ncurses
1241 is configured to use the GPM interface,
1242 this variable may list one or more terminal names
1243 against which the
1244 .I TERM
1245 variable
1246 (see below)
1247 is matched.
1248 An empty value disables the GPM interface,
1249 using
1250 .IR \%ncurses 's
1251 built-in support for \fIxterm\fP(1) mouse protocols instead.
1252 If the variable is absent,
1253 .I \%ncurses
1254 attempts to open GPM if
1255 .I TERM
1256 contains \*(``linux\*(''.
1257 .SS "\fINCURSES_NO_HARD_TABS\fP"
1258 .I \%ncurses
1259 may use tab characters in cursor movement optimization.
1260 In some cases,
1261 your terminal driver may not handle them properly.
1262 Set this environment variable to any value to disable the feature.
1263 You can also adjust your \fI\%stty\fP(1) settings to avoid the problem.
1264 .SS "\fINCURSES_NO_MAGIC_COOKIE\fP"
1265 Many terminals store video attributes as a property of a character cell,
1266 as
1267 .I curses
1268 does.
1269 Historically,
1270 some recorded changes in video attributes as data that logically
1271 .I occupies
1272 character cells on the display,
1273 switching attributes on or off,
1274 similarly to tags in a markup language;
1275 these are termed \*(``magic cookies\*('',
1276 and must be subsequently overprinted.
1277 If the
1278 .I \%term\%info
1279 entry for your terminal type does not adequately describe its handling
1280 of magic cookies,
1281 set this variable to any value to instruct
1282 .I \%ncurses
1283 to disable attributes entirely.
1284 .SS "\fINCURSES_NO_PADDING\fP"
1285 Most terminal type descriptions in the
1286 .I \%term\%info
1287 database detail hardware devices.
1288 Many people use
1289 .IR curses -based
1290 applications in terminal emulator programs that run in a windowing
1291 environment.
1292 These programs can duplicate all of the important features of a hardware
1293 terminal,
1294 but often lack their limitations.
1295 Chief among these absent drawbacks is the problem of data flow
1296 management;
1297 that is,
1298 limiting the speed of communication to what the hardware could handle.
1299 Unless a hardware terminal is interfaced into a terminal concentrator
1300 (which does flow control),
1301 an application must manage flow control itself to prevent overruns and
1302 data loss.
1303 .PP
1304 A solution that comes at no hardware cost is for an application to pause
1305 after directing a terminal to execute an operation that it performs
1306 slowly,
1307 such as clearing the display.
1308 Many terminal type descriptions,
1309 including that for the VT100,
1310 embed delay specifications in capabilities.
1311 You may wish to use these temrinal descriptions without paying the
1312 performance penalty.
1313 Set
1314 .I \%NCURSES_NO_PADDING
1315 to any value to disable all but mandatory padding.
1316 Mandatory padding is used by such terminal capabilities as
1317 .B \%flash_screen
1318 .RB ( flash ).
1319 .SS "\fINCURSES_NO_SETBUF\fP"
1320 (Obsolete)
1321 Prior to internal changes developed in
1322 .I \%ncurses
1323 5.9
1324 (patches 20120825 through 20130126),
1325 the library used \fI\%setbuf\fP(3) to enable fully buffered output when
1326 initializing the terminal.
1327 This was done,
1328 as in SVr4
1329 .IR curses ,
1330 to increase performance.
1331 For testing purposes,
1332 both of
1333 .I \%ncurses
1334 and of certain applications,
1335 this feature was made optional.
1336 Setting this variable disabled output buffering,
1337 leaving the output stream in the original
1338 (usually line-buffered)
1339 mode.
1340 .PP
1341 Nowadays,
1342 .I \%ncurses
1343 performs its own buffering and does not require this workaround;
1344 it does not modify the buffering of the standard output stream.
1345 This approach makes signal handling,
1346 as for interrupts,
1347 more robust.
1348 A drawback is that certain unconventional programs mixed
1349 \fI\%stdio\fP(3) calls with
1350 .I \%ncurses
1351 calls and (usually)
1352 got the behavior they expected.
1353 This is no longer the case;
1354 .I \%ncurses
1355 does not write to the standard output file descriptor through a
1356 .IR stdio -buffered
1357 stream.
1358 .PP
1359 As a special case,
1360 low-level API calls such as \fB\%putp\fP(3X) still use the
1361 standard output stream.
1362 High-level
1363 .I curses
1364 calls such as \fB\%printw\fP(3X) do not.
1365 .SS "\fINCURSES_NO_UTF8_ACS\fP"
1366 At initialization,
1367 .I \%ncurses
1368 inspects the
1369 .I TERM
1370 environment variable for special cases where VT100 forms-drawing
1371 characters
1372 (and the corresponding alternate character set
1373 .I \%term\%info
1374 capabilities)
1375 are known to be unsupported by terminal types that otherwise claim VT100
1376 compatibility.
1377 Specifically,
1378 when running in a UTF-8 locale,
1379 the Linux virtual console device and the GNU \fI\%screen\fP(1)
1380 program ignore them.
1381 Set this variable to a nonzero value to instruct
1382 .I \%ncurses
1383 that the terminal's ACS support is broken;
1384 the library then outputs Unicode code points that correspond to the
1385 forms-drawing
1386 characters.
1387 Set it to zero
1388 (or a non-integer)
1389 to disable the special check for terminal type names matching
1390 \*(``linux\*('' or \*(``screen\*('',
1391 directing
1392 .I \%ncurses
1393 to assume that the ACS feature works if the terminal type description
1394 advertises it.
1395 .PP
1396 As an alternative to use of this variable,
1397 .I \%ncurses
1398 checks for an extended
1399 .I \%term\%info
1400 numeric capability \fBU8\fP
1401 that can be compiled using
1402 .RB \*(`` "@TIC@ \-x" \*(''.
1403 Examples follow.
1404 .PP
1405 .RS 3
1406 .EX
1407 # linux console, if patched to provide working
1408 # VT100 shift\-in/shift\-out, with corresponding font.
1409 linux\-vt100|linux console with VT100 line\-graphics,
1410         U8#0, use=linux,
1411 \&
1412 # uxterm with vt100Graphics resource set to false
1413 xterm\-utf8|xterm relying on UTF\-8 line\-graphics,
1414         U8#1, use=xterm,
1415 .EE
1416 .RE
1417 .PP
1418 The two-character name \*(``U8\*('' was chosen to permit its use via
1419 .IR \%ncurses 's
1420 .I termcap
1421 interface.
1422 .SS "\fINCURSES_TRACE\fP"
1423 At initialization,
1424 .I \%ncurses
1425 (in its debugging configuration)
1426 checks for this variable's presence.
1427 If defined with an integral value,
1428 the library calls \fB\%curses_trace\fP(3X) with that value as the
1429 argument.
1430 .SS "\fITERM\fP"
1431 Denotes your terminal type.
1432 Each terminal type is distinct, though many are similar.
1433 .PP
1434 \fITERM\fP is commonly set by terminal emulators to help
1435 applications find a workable terminal description.
1436 Some of those choose a popular approximation, e.g.,
1437 \*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit.
1438 Not infrequently, your application will have problems with that approach,
1439 e.g., incorrect function-key definitions.
1440 .PP
1441 If you set \fITERM\fP in your environment,
1442 it has no effect on the operation of the terminal emulator.
1443 It only affects the way applications work within the terminal.
1444 Likewise, as a general rule (\fBxterm\fP(1) being a rare exception),
1445 terminal emulators which allow you to
1446 specify \fITERM\fP as a parameter or configuration value do
1447 not change their behavior to match that setting.
1448 .SS "\fITERMCAP\fP"
1449 If the \fI\%ncurses\fP library has been configured with \fItermcap\fP
1450 support, \fI\%ncurses\fP will check for a terminal's description in
1451 termcap form if it is not available in the terminfo database.
1452 .PP
1453 The \fI\%TERMCAP\fP environment variable contains
1454 either a terminal description (with newlines stripped out),
1455 or a file name telling where the information denoted by
1456 the \fITERM\fP environment variable exists.
1457 In either case, setting it directs \fI\%ncurses\fP to ignore
1458 the usual place for this information, e.g., /etc/termcap.
1459 .SS "\fITERMINFO\fP"
1460 \fI\%ncurses\fP can be configured to read from multiple terminal
1461 databases.
1462 The \fI\%TERMINFO\fP variable overrides the location for
1463 the default terminal database.
1464 Terminal descriptions (in terminal format) are stored in terminal databases:
1465 .bP
1466 Normally these are stored in a directory tree,
1467 using subdirectories named by the first letter of the terminal names therein.
1468 .IP
1469 This is the scheme used in System V, which legacy Unix systems use,
1470 and the \fI\%TERMINFO\fP variable is used by \fIcurses\fP applications
1471 on those
1472 systems to override the default location of the terminal database.
1473 .IP \(bu 4
1474 If \fI\%ncurses\fP is built to use hashed databases,
1475 then each entry in this list may be the path of a hashed database file, e.g.,
1476 .RS 4
1477 .PP
1478 .RS 4
1479 .EX
1480 /usr/share/terminfo.db
1481 .EE
1482 .RE
1483 .PP
1484 rather than
1485 .PP
1486 .RS 4
1487 .EX
1488 /usr/share/terminfo/
1489 .EE
1490 .RE
1491 .PP
1492 The hashed database uses less disk-space and is a little faster than the
1493 directory tree.
1494 However,
1495 some applications assume the existence of the directory tree,
1496 reading it directly
1497 rather than using the terminfo library calls.
1498 .RE
1499 .bP
1500 If \fI\%ncurses\fP is built with a support for reading termcap files
1501 directly, then an entry in this list may be the path of a termcap file.
1502 .IP \(bu 4
1503 If the \fI\%TERMINFO\fP variable begins with
1504 \*(``hex:\*('' or \*(``b64:\*('',
1505 \fI\%ncurses\fP uses the remainder of that variable as a compiled
1506 terminal description.
1507 You might produce the base64 format using \fBinfocmp\fP(1M):
1508 .RS 4
1509 .PP
1510 .RS 4
1511 .EX
1512 TERMINFO="$(infocmp \-0 \-Q2 \-q)"
1513 export TERMINFO
1514 .EE
1515 .RE
1516 .PP
1517 The compiled description is used if it corresponds to the terminal identified
1518 by the \fITERM\fP variable.
1519 .RE
1520 .PP
1521 Setting \fI\%TERMINFO\fP is the simplest,
1522 but not the only way to set location of the default terminal database.
1523 The complete list of database locations in order follows:
1524 .RS 3
1525 .bP
1526 the last terminal database to which \fI\%ncurses\fP wrote,
1527 if any, is searched first
1528 .bP
1529 the location specified by the \fI\%TERMINFO\fP environment variable
1530 .bP
1531 $HOME/.terminfo
1532 .bP
1533 locations listed in the \fI\%TERMINFO_DIRS\fP environment variable
1534 .bP
1535 one or more locations whose names are configured and compiled into the
1536 \fI\%ncurses\fP library, i.e.,
1537 .RS 3
1538 .bP
1539 @TERMINFO_DIRS@ (corresponding to the \fI\%TERMINFO_DIRS\fP variable)
1540 .bP
1541 @TERMINFO@ (corresponding to the \fITERMINFO\fP variable)
1542 .RE
1543 .RE
1544 .SS "\fITERMINFO_DIRS\fP"
1545 Specifies a list of locations to search for terminal descriptions.
1546 Each location in the list is a terminal database as described in
1547 the section on the \fI\%TERMINFO\fP variable.
1548 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1549 .PP
1550 There is no corresponding feature in System V terminfo;
1551 it is an extension developed for \fI\%ncurses\fP.
1552 .SS "\fITERMPATH\fP"
1553 If \fI\%TERMCAP\fP does not hold a file name then \fI\%ncurses\fP checks
1554 the \fI\%TERMPATH\fP environment variable.
1555 This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
1556 semicolons on OS/2 EMX.
1557 .PP
1558 If the \fI\%TERMPATH\fP environment variable is not set,
1559 \fI\%ncurses\fP looks in the files
1560 .PP
1561 .RS 4
1562 .EX
1563 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
1564 .EE
1565 .RE
1566 .PP
1567 in that order.
1568 .SH "ALTERNATE CONFIGURATIONS"
1569 Many different
1570 .I \%ncurses
1571 configurations are possible,
1572 determined by the options given to the
1573 .I \%configure
1574 script when building the library.
1575 Run the script with the
1576 .B \-\-help
1577 option to peruse them all.
1578 A few are of particular significance to the application developer
1579 employing
1580 .IR \%ncurses .
1581 .TP 5
1582 \-\-disable\-overwrite
1583 The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP:
1584 .RS 5
1585 .PP
1586 .RS 4
1587 .EX
1588 \fB#include <curses.h>\fP
1589 .EE
1590 .RE
1591 .PP
1592 This option is used to avoid filename conflicts when \fI\%ncurses\fP
1593 is not the main implementation of curses of the computer.
1594 If \fI\%ncurses\fP is installed disabling overwrite,
1595 it puts its headers in a subdirectory,
1596 e.g.,
1597 .PP
1598 .RS 4
1599 .EX
1600 \fB#include <ncurses/curses.h>\fP
1601 .EE
1602 .RE
1603 .PP
1604 It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
1605 to build executables.
1606 .RE
1607 .TP 5
1608 \-\-enable\-widec
1609 The configure script renames the library and
1610 (if the \fB\-\-disable\-overwrite\fP option is used)
1611 puts the header files in a different subdirectory.
1612 All of the library names have a \*(``w\*('' appended to them,
1613 i.e., instead of
1614 .RS 5
1615 .PP
1616 .RS 4
1617 .EX
1618 \fB\-lncurses\fP
1619 .EE
1620 .RE
1621 .PP
1622 you link with
1623 .PP
1624 .RS 4
1625 .EX
1626 \fB\-lncursesw\fP
1627 .EE
1628 .RE
1629 .PP
1630 You must also enable the wide-character features in the header file
1631 when compiling for the wide-character library
1632 to use the extended (wide-character) functions.
1633 The symbol which enables these features has changed since XSI Curses, Issue 4:
1634 .bP
1635 Originally, the wide-character feature required the symbol
1636 \fB_XOPEN_SOURCE_EXTENDED\fP
1637 but that was only valid for XPG4 (1996).
1638 .bP
1639 Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500.
1640 .bP
1641 As of mid-2018,
1642 none of the features in this implementation require a \fB_XOPEN_SOURCE\fP
1643 feature greater than 600.
1644 However, X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1645 .bP
1646 Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP
1647 with the caveat that some other header file than \fBcurses.h\fP
1648 may require a specific value for \fB_XOPEN_SOURCE\fP
1649 (or a system-specific symbol).
1650 .PP
1651 The \fI\%curses.h\fP header file installed for the wide-character
1652 library is designed to be compatible with the non-wide library's header.
1653 Only the size of the \fI\%WINDOW\fP structure differs;
1654 few applications require more than pointers to \fI\%WINDOW\fPs.
1655 .PP
1656 If the headers are installed allowing overwrite,
1657 the wide-character library's headers should be installed last,
1658 to allow applications to be built using either library
1659 from the same set of headers.
1660 .RE
1661 .TP 5
1662 \-\-with\-pthread
1663 The configure script renames the library.
1664 All of the library names have a \*(``t\*('' appended to them
1665 (before any \*(``w\*('' added by \fB\-\-enable\-widec\fP).
1666 .IP
1667 The global variables such as \fBLINES\fP are replaced by macros to
1668 allow read-only access.
1669 At the same time, setter-functions are provided to set these values.
1670 Some applications (very few) may require changes to work with this convention.
1671 .TP 5
1672 \-\-with\-shared
1673 .TP
1674 \-\-with\-normal
1675 .TP
1676 \-\-with\-debug
1677 .TP
1678 \-\-with\-profile
1679 The shared and normal (static) library names differ by their suffixes,
1680 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
1681 The debug and profiling libraries add a \*(``_g\*(''
1682 and a \*(``_p\*('' to the root names respectively,
1683 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
1684 .TP 5
1685 \-\-with\-termlib
1686 Low-level functions which do not depend upon whether the library
1687 supports wide-characters, are provided in the tinfo library.
1688 .IP
1689 By doing this, it is possible to share the tinfo library between
1690 wide/normal configurations as well as reduce the size of the library
1691 when only low-level functions are needed.
1692 .IP
1693 Those functions are described in these pages:
1694 .RS
1695 .bP
1696 \fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
1697 .bP
1698 \fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
1699 .bP
1700 \fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
1701 .bP
1702 \fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
1703 .bP
1704 \fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
1705 .bP
1706 \fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
1707 database
1708 .bP
1709 \fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
1710 .RE
1711 .TP 5
1712 \-\-with\-trace
1713 The \fBtrace\fP function normally resides in the debug library,
1714 but it is sometimes useful to configure this in the shared library.
1715 Configure scripts should check for the function's existence rather
1716 than assuming it is always in the debug library.
1717 .SH FILES
1718 .TP
1719 .I @DATADIR@/tabset
1720 tab stop initialization database
1721 .TP
1722 .I \*d
1723 compiled terminal capability database
1724 .SH NOTES
1725 X/Open Curses permits most functions it specifies to be made available
1726 as macros as well.
1727 .\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
1728 .\" See X/Open Curses Issue 7, pp. 311-318.
1729 \fI\%ncurses\fP does so
1730 .bP
1731 for functions that return values via their parameters,
1732 .bP
1733 to support obsolete features,
1734 .bP
1735 to reuse functions
1736 (for example,
1737 those that move the cursor before another operation),
1738 and
1739 .bP
1740 a few special cases.
1741 .PP
1742 If the standard output file descriptor of an
1743 .I \%ncurses
1744 program is redirected to something that is not a terminal device,
1745 the library writes screen updates to the standard error file descriptor.
1746 This was an undocumented feature of SVr3.
1747 .PP
1748 See subsection \*(``Header files\*('' below regarding symbols exposed by
1749 inclusion of \fI\%curses.h\fP.
1750 .SH EXTENSIONS
1751 .I \%ncurses
1752 enables an application to capture mouse events on certain terminals,
1753 including
1754 .IR \%xterm ;
1755 see \fB\%curs_mouse\fP(3X).
1756 .PP
1757 .I \%ncurses
1758 provides a means of responding to window resizing events,
1759 as when running in a GUI terminal emulator application such as
1760 .IR \%xterm ;
1761 see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
1762 .PP
1763 .I \%ncurses
1764 allows an application to query the terminal for the presence of a wide
1765 variety of special keys;
1766 see \fB\%has_key\fP(3X).
1767 .PP
1768 .I \%ncurses
1769 extends the fixed set of function key capabilities specified by X/Open
1770 Curses by allowing the application programmer to define additional key
1771 sequences at runtime;
1772 see
1773 \fB\%define_key\fP(3X),
1774 \fB\%key_defined\fP(3X),
1775 and
1776 \fB\%keyok\fP(3X).
1777 .PP
1778 .I \%ncurses
1779 can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
1780 SGR\ 39 and SGR\ 49 sequences,
1781 which allow an application to reset the terminal to its original
1782 foreground and background colors.
1783 From a user's perspective,
1784 the application is able to draw colored text on a background whose color
1785 is set independently,
1786 providing better control over color contrasts.
1787 See \fB\%default_colors\fP(3X).
1788 .PP
1789 An
1790 .I \%ncurses
1791 application can choose to hide the internal details of
1792 .I \%WINDOW
1793 structures,
1794 instead using accessor functions such as
1795 \fB\%is_scrollok\fP(3X).
1796 .PP
1797 .I \%ncurses
1798 enables an application to direct application output to a printer
1799 attached to the terminal device;
1800 see \fB\%curs_print\fP(3X).
1801 .PP
1802 .I \%ncurses
1803 offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for
1804 soft-label key lines,
1805 and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
1806 that can gather color information from them when many colors are
1807 supported.
1808 .PP
1809 Some extensions are only available if
1810 .I \%ncurses
1811 is compiled to support them;
1812 section \*(``ALTERNATE CONFIGURATIONS\*('' describes how.
1813 .bP
1814 Rudimentary support for multi-threaded applications may be available;
1815 see \fBcurs_threads\fP(3X).
1816 .bP
1817 Functions that ease the management of multiple screens can be exposed;
1818 see \fBcurs_sp_funcs\fP(3X).
1819 .bP
1820 To aid applications to debug their memory usage,
1821 .I ncurses
1822 optionally offers functions to more aggressively free memory it
1823 dynamically allocates itself;
1824 see \fBcurs_memleaks\fP(3X).
1825 .bP
1826 The library facilitates auditing and troubleshooting of its behavior;
1827 see \fBcurs_trace\fP(3X).
1828 .bP
1829 The compiler option
1830 .B \%\-DUSE_GETCAP
1831 causes the library to fall back to reading
1832 .I \%/etc/termcap
1833 if the terminal setup code cannot find a
1834 .I \%term\%info
1835 entry corresponding to
1836 .IR TERM .
1837 Use of this feature is not recommended,
1838 as it essentially includes an entire
1839 .I termcap
1840 compiler in the
1841 .I \%ncurses
1842 startup code,
1843 at a cost in memory usage and application launch latency.
1844 .PP
1845 .I \%PDCurses
1846 and NetBSD
1847 .I curses
1848 incorporate some
1849 .I \%ncurses
1850 extensions.
1851 Individual man pages indicate where this is the case.
1852 .SH PORTABILITY
1853 X/Open Curses defines two levels of conformance,
1854 \*(``base\*('' and \*(``enhanced\*(''.
1855 The latter includes several additional features,
1856 such as wide-character and color support.
1857 .I \%ncurses
1858 intends base-level conformance with X/Open Curses,
1859 and supports nearly all its enhanced features.
1860 .\" XXX: What's missing?  GBR counts untic(1), and that's all.
1861 .PP
1862 Differences between X/Open Curses and
1863 .I \%ncurses
1864 are documented in the \*(``PORTABILITY\*('' sections of applicable man
1865 pages.
1866 .SS "Error Checking"
1867 In many cases, X/Open Curses is vague about error conditions,
1868 omitting some of the SVr4 documentation.
1869 .PP
1870 Unlike other implementations, this one checks parameters such as pointers
1871 to \fI\%WINDOW\fP structures to ensure they are not null.
1872 The main reason for providing this behavior is to guard against programmer
1873 error.
1874 The standard interface does not provide a way for the library
1875 to tell an application which of several possible errors were detected.
1876 Relying on this (or some other) extension will adversely affect the
1877 portability of curses applications.
1878 .SS "Padding Differences"
1879 In historic curses versions, delays embedded in the capabilities \fBcr\fP,
1880 \fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay
1881 bits in the Unix tty driver.
1882 In this implementation, all padding is done by sending NUL bytes.
1883 This method is slightly more expensive, but narrows the interface
1884 to the Unix kernel significantly and increases the package's portability
1885 correspondingly.
1886 .SS "Header Files"
1887 The header file \fI\%curses.h\fP itself includes the header files
1888 \fI\%stdio.h\fP and \fI\%unctrl.h\fP.
1889 .PP
1890 X/Open Curses has more to say,
1891 but does not finish the story:
1892 .RS 4
1893 .PP
1894 The inclusion of <curses.h> may make visible all symbols
1895 from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
1896 .RE
1897 .PP
1898 Here is a more complete story:
1899 .bP
1900 Starting with BSD curses, all implementations have included <stdio.h>.
1901 .IP
1902 BSD curses included <curses.h> and <unctrl.h> from an internal header
1903 file
1904 .I \%curses.ext
1905 (\*(``ext\*('' abbreviated \*(``externs\*('').
1906 .IP
1907 BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP),
1908 but nothing in <curses.h> itself relied upon <stdio.h>.
1909 .bP
1910 SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>.
1911 That is, the function prototype uses \fBFILE\fP.
1912 .IP
1913 SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>.
1914 .IP
1915 X/Open Curses documents all three of these functions.
1916 .IP
1917 SVr4 curses and X/Open Curses do not require the developer to
1918 include <stdio.h> before including <curses.h>.
1919 Both document curses showing <curses.h> as the only required header.
1920 .IP
1921 As a result, standard <curses.h> will always include <stdio.h>.
1922 .bP
1923 X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>.
1924 .IP
1925 As noted in \fBcurs_util\fP(3X),
1926 \fI\%ncurses\fP includes <unctrl.h> from <curses.h>
1927 (like SVr4).
1928 .bP
1929 X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX:
1930 .IP
1931 HP-UX curses includes <term.h> from <curses.h>
1932 to declare \fBsetupterm\fP in curses.h,
1933 but \fI\%ncurses\fP (and Solaris curses) do not.
1934 .IP
1935 AIX curses includes <term.h> and <termios.h>.
1936 Again, \fI\%ncurses\fP (and Solaris curses) do not.
1937 .bP
1938 X/Open says that <curses.h> \fImay\fP include <term.h>,
1939 but there is no requirement that it do that.
1940 .IP
1941 Some programs use functions declared in both <curses.h> and <term.h>,
1942 and must include both headers in the same module.
1943 Very old versions of AIX curses required including <curses.h>
1944 before including <term.h>.
1945 .IP
1946 Because \fI\%ncurses\fP header files include the headers needed to
1947 define datatypes used in the headers,
1948 \fI\%ncurses\fP header files can be included in any order.
1949 But for portability, you should include <curses.h> before <term.h>.
1950 .bP
1951 X/Open Curses says \fI"may make visible"\fP
1952 because including a header file does not necessarily make all symbols
1953 in it visible (there are ifdef's to consider).
1954 .IP
1955 For instance, in \fI\%ncurses\fP <wchar.h> \fImay\fP be included if
1956 the proper symbol is defined, and if \fI\%ncurses\fP is configured for
1957 wide-character support.
1958 If the header is included, its symbols may be made visible.
1959 That depends on the value used for \fB_XOPEN_SOURCE\fP
1960 feature test macro.
1961 .bP
1962 X/Open Curses documents one required header,
1963 in a special case: <stdarg.h> before <curses.h> to prototype
1964 the \fBvw_printw\fP and \fBvw_scanw\fP functions
1965 (as well as the obsolete
1966 the \fBvwprintw\fP and \fBvwscanw\fP functions).
1967 Each of those uses a \fBva_list\fP parameter.
1968 .IP
1969 The two obsolete functions were introduced in SVr3.
1970 The other functions were introduced in X/Open Curses.
1971 In between, SVr4 curses provided for the possibility that
1972 an application might include either <varargs.h> or <stdarg.h>.
1973 Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP
1974 parameter.
1975 Later, a special type (defined in <stdio.h>) was introduced,
1976 to allow for compiler type-checking.
1977 That special type is always available,
1978 because <stdio.h> is always included by <curses.h>.
1979 .IP
1980 None of the X/Open Curses implementations require an application
1981 to include <stdarg.h> before <curses.h> because they either
1982 have allowed for a special type,
1983 or
1984 (like \fI\%ncurses\fP)
1985 include <stdarg.h> directly to provide a portable interface.
1986 .SH AUTHORS
1987 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1988 Based on \fIpcurses\fP by Pavel Curtis.
1989 .SH SEE ALSO
1990 \fB\%curs_variables\fP(3X),
1991 \fB\%terminfo\fP(5),
1992 \fB\%user_caps\fP(5)