man/ncurses.3x

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