man/ncurses.3x

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright (c) 1998-2005,2006 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.82 2006/12/24 14:44:05 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 getbegyx/\fBcurs_getyx\fR(3X)
 279 getbkgd/\fBcurs_bkgd\fR(3X)
 280 getbkgrnd/\fBcurs_bkgrnd\fR(3X)
 281 getcchar/\fBcurs_getcchar\fR(3X)
 282 getch/\fBcurs_getch\fR(3X)
 283 getmaxyx/\fBcurs_getyx\fR(3X)
 284 getmouse/\fBcurs_mouse\fR(3X)*
 285 getn_wstr/\fBcurs_get_wstr\fR(3X)
 286 getnstr/\fBcurs_getstr\fR(3X)
 287 getparyx/\fBcurs_getyx\fR(3X)
 288 getstr/\fBcurs_getstr\fR(3X)
 289 getsyx/\fBcurs_kernel\fR(3X)
 290 getwin/\fBcurs_util\fR(3X)
 291 getyx/\fBcurs_getyx\fR(3X)
 292 halfdelay/\fBcurs_inopts\fR(3X)
 293 has_colors/\fBcurs_color\fR(3X)
 294 has_ic/\fBcurs_termattrs\fR(3X)
 295 has_il/\fBcurs_termattrs\fR(3X)
 296 has_key/\fBcurs_getch\fR(3X)*
 297 hline/\fBcurs_border\fR(3X)
 298 hline_set/\fBcurs_border_set\fR(3X)
 299 idcok/\fBcurs_outopts\fR(3X)
 300 idlok/\fBcurs_outopts\fR(3X)
 301 immedok/\fBcurs_outopts\fR(3X)
 302 in_wch/\fBcurs_in_wch\fR(3X)
 303 in_wchnstr/\fBcurs_in_wchstr\fR(3X)
 304 in_wchstr/\fBcurs_in_wchstr\fR(3X)
 305 inch/\fBcurs_inch\fR(3X)
 306 inchnstr/\fBcurs_inchstr\fR(3X)
 307 inchstr/\fBcurs_inchstr\fR(3X)
 308 init_color/\fBcurs_color\fR(3X)
 309 init_pair/\fBcurs_color\fR(3X)
 310 initscr/\fBcurs_initscr\fR(3X)
 311 innstr/\fBcurs_instr\fR(3X)
 312 innwstr/\fBcurs_inwstr\fR(3X)
 313 ins_nwstr/\fBcurs_ins_wstr\fR(3X)
 314 ins_wch/\fBcurs_ins_wch\fR(3X)
 315 ins_wstr/\fBcurs_ins_wstr\fR(3X)
 316 insch/\fBcurs_insch\fR(3X)
 317 insdelln/\fBcurs_deleteln\fR(3X)
 318 insertln/\fBcurs_deleteln\fR(3X)
 319 insnstr/\fBcurs_insstr\fR(3X)
 320 insstr/\fBcurs_insstr\fR(3X)
 321 instr/\fBcurs_instr\fR(3X)
 322 intrflush/\fBcurs_inopts\fR(3X)
 323 inwstr/\fBcurs_inwstr\fR(3X)
 324 is_linetouched/\fBcurs_touch\fR(3X)
 325 is_wintouched/\fBcurs_touch\fR(3X)
 326 isendwin/\fBcurs_initscr\fR(3X)
 327 key_defined/\fBkey_defined\fR(3X)*
 328 key_name/\fBcurs_util\fR(3X)
 329 keybound/\fBkeybound\fR(3X)*
 330 keyname/\fBcurs_util\fR(3X)
 331 keyok/\fBkeyok\fR(3X)*
 332 keypad/\fBcurs_inopts\fR(3X)
 333 killchar/\fBcurs_termattrs\fR(3X)
 334 killwchar/\fBcurs_termattrs\fR(3X)
 335 leaveok/\fBcurs_outopts\fR(3X)
 336 longname/\fBcurs_termattrs\fR(3X)
 337 mcprint/\fBcurs_print\fR(3X)*
 338 meta/\fBcurs_inopts\fR(3X)
 339 mouse_trafo/\fBcurs_mouse\fR(3X)*
 340 mouseinterval/\fBcurs_mouse\fR(3X)*
 341 mousemask/\fBcurs_mouse\fR(3X)*
 342 move/\fBcurs_move\fR(3X)
 343 mvadd_wch/\fBcurs_add_wch\fR(3X)
 344 mvadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
 345 mvadd_wchstr/\fBcurs_add_wchstr\fR(3X)
 346 mvaddch/\fBcurs_addch\fR(3X)
 347 mvaddchnstr/\fBcurs_addchstr\fR(3X)
 348 mvaddchstr/\fBcurs_addchstr\fR(3X)
 349 mvaddnstr/\fBcurs_addstr\fR(3X)
 350 mvaddnwstr/\fBcurs_addwstr\fR(3X)
 351 mvaddstr/\fBcurs_addstr\fR(3X)
 352 mvaddwstr/\fBcurs_addwstr\fR(3X)
 353 mvchgat/\fBcurs_attr\fR(3X)
 354 mvcur/\fBcurs_terminfo\fR(3X)
 355 mvdelch/\fBcurs_delch\fR(3X)
 356 mvderwin/\fBcurs_window\fR(3X)
 357 mvget_wch/\fBcurs_get_wch\fR(3X)
 358 mvget_wstr/\fBcurs_get_wstr\fR(3X)
 359 mvgetch/\fBcurs_getch\fR(3X)
 360 mvgetn_wstr/\fBcurs_get_wstr\fR(3X)
 361 mvgetnstr/\fBcurs_getstr\fR(3X)
 362 mvgetstr/\fBcurs_getstr\fR(3X)
 363 mvhline/\fBcurs_border\fR(3X)
 364 mvhline_set/\fBcurs_border_set\fR(3X)
 365 mvin_wch/\fBcurs_in_wch\fR(3X)
 366 mvin_wchnstr/\fBcurs_in_wchstr\fR(3X)
 367 mvin_wchstr/\fBcurs_in_wchstr\fR(3X)
 368 mvinch/\fBcurs_inch\fR(3X)
 369 mvinchnstr/\fBcurs_inchstr\fR(3X)
 370 mvinchstr/\fBcurs_inchstr\fR(3X)
 371 mvinnstr/\fBcurs_instr\fR(3X)
 372 mvinnwstr/\fBcurs_inwstr\fR(3X)
 373 mvins_nwstr/\fBcurs_ins_wstr\fR(3X)
 374 mvins_wch/\fBcurs_ins_wch\fR(3X)
 375 mvins_wstr/\fBcurs_ins_wstr\fR(3X)
 376 mvinsch/\fBcurs_insch\fR(3X)
 377 mvinsnstr/\fBcurs_insstr\fR(3X)
 378 mvinsstr/\fBcurs_insstr\fR(3X)
 379 mvinstr/\fBcurs_instr\fR(3X)
 380 mvinwstr/\fBcurs_inwstr\fR(3X)
 381 mvprintw/\fBcurs_printw\fR(3X)
 382 mvscanw/\fBcurs_scanw\fR(3X)
 383 mvvline/\fBcurs_border\fR(3X)
 384 mvvline_set/\fBcurs_border_set\fR(3X)
 385 mvwadd_wch/\fBcurs_add_wch\fR(3X)
 386 mvwadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
 387 mvwadd_wchstr/\fBcurs_add_wchstr\fR(3X)
 388 mvwaddch/\fBcurs_addch\fR(3X)
 389 mvwaddchnstr/\fBcurs_addchstr\fR(3X)
 390 mvwaddchstr/\fBcurs_addchstr\fR(3X)
 391 mvwaddnstr/\fBcurs_addstr\fR(3X)
 392 mvwaddnwstr/\fBcurs_addwstr\fR(3X)
 393 mvwaddstr/\fBcurs_addstr\fR(3X)
 394 mvwaddwstr/\fBcurs_addwstr\fR(3X)
 395 mvwchgat/\fBcurs_attr\fR(3X)
 396 mvwdelch/\fBcurs_delch\fR(3X)
 397 mvwget_wch/\fBcurs_get_wch\fR(3X)
 398 mvwget_wstr/\fBcurs_get_wstr\fR(3X)
 399 mvwgetch/\fBcurs_getch\fR(3X)
 400 mvwgetn_wstr/\fBcurs_get_wstr\fR(3X)
 401 mvwgetnstr/\fBcurs_getstr\fR(3X)
 402 mvwgetstr/\fBcurs_getstr\fR(3X)
 403 mvwhline/\fBcurs_border\fR(3X)
 404 mvwhline_set/\fBcurs_border_set\fR(3X)
 405 mvwin/\fBcurs_window\fR(3X)
 406 mvwin_wch/\fBcurs_in_wch\fR(3X)
 407 mvwin_wchnstr/\fBcurs_in_wchstr\fR(3X)
 408 mvwin_wchstr/\fBcurs_in_wchstr\fR(3X)
 409 mvwinch/\fBcurs_inch\fR(3X)
 410 mvwinchnstr/\fBcurs_inchstr\fR(3X)
 411 mvwinchstr/\fBcurs_inchstr\fR(3X)
 412 mvwinnstr/\fBcurs_instr\fR(3X)
 413 mvwinnwstr/\fBcurs_inwstr\fR(3X)
 414 mvwins_nwstr/\fBcurs_ins_wstr\fR(3X)
 415 mvwins_wch/\fBcurs_ins_wch\fR(3X)
 416 mvwins_wstr/\fBcurs_ins_wstr\fR(3X)
 417 mvwinsch/\fBcurs_insch\fR(3X)
 418 mvwinsnstr/\fBcurs_insstr\fR(3X)
 419 mvwinsstr/\fBcurs_insstr\fR(3X)
 420 mvwinstr/\fBcurs_instr\fR(3X)
 421 mvwinwstr/\fBcurs_inwstr\fR(3X)
 422 mvwprintw/\fBcurs_printw\fR(3X)
 423 mvwscanw/\fBcurs_scanw\fR(3X)
 424 mvwvline/\fBcurs_border\fR(3X)
 425 mvwvline_set/\fBcurs_border_set\fR(3X)
 426 napms/\fBcurs_kernel\fR(3X)
 427 newpad/\fBcurs_pad\fR(3X)
 428 newterm/\fBcurs_initscr\fR(3X)
 429 newwin/\fBcurs_window\fR(3X)
 430 nl/\fBcurs_outopts\fR(3X)
 431 nocbreak/\fBcurs_inopts\fR(3X)
 432 nodelay/\fBcurs_inopts\fR(3X)
 433 noecho/\fBcurs_inopts\fR(3X)
 434 nonl/\fBcurs_outopts\fR(3X)
 435 noqiflush/\fBcurs_inopts\fR(3X)
 436 noraw/\fBcurs_inopts\fR(3X)
 437 notimeout/\fBcurs_inopts\fR(3X)
 438 overlay/\fBcurs_overlay\fR(3X)
 439 overwrite/\fBcurs_overlay\fR(3X)
 440 pair_content/\fBcurs_color\fR(3X)
 441 pechochar/\fBcurs_pad\fR(3X)
 442 pnoutrefresh/\fBcurs_pad\fR(3X)
 443 prefresh/\fBcurs_pad\fR(3X)
 444 printw/\fBcurs_printw\fR(3X)
 445 putp/\fBcurs_terminfo\fR(3X)
 446 putwin/\fBcurs_util\fR(3X)
 447 qiflush/\fBcurs_inopts\fR(3X)
 448 raw/\fBcurs_inopts\fR(3X)
 449 redrawwin/\fBcurs_refresh\fR(3X)
 450 refresh/\fBcurs_refresh\fR(3X)
 451 reset_prog_mode/\fBcurs_kernel\fR(3X)
 452 reset_shell_mode/\fBcurs_kernel\fR(3X)
 453 resetty/\fBcurs_kernel\fR(3X)
 454 resizeterm/\fBresizeterm\fR(3X)*
 455 restartterm/\fBcurs_terminfo\fR(3X)
 456 ripoffline/\fBcurs_kernel\fR(3X)
 457 savetty/\fBcurs_kernel\fR(3X)
 458 scanw/\fBcurs_scanw\fR(3X)
 459 scr_dump/\fBcurs_scr_dump\fR(3X)
 460 scr_init/\fBcurs_scr_dump\fR(3X)
 461 scr_restore/\fBcurs_scr_dump\fR(3X)
 462 scr_set/\fBcurs_scr_dump\fR(3X)
 463 scrl/\fBcurs_scroll\fR(3X)
 464 scroll/\fBcurs_scroll\fR(3X)
 465 scrollok/\fBcurs_outopts\fR(3X)
 466 set_curterm/\fBcurs_terminfo\fR(3X)
 467 set_term/\fBcurs_initscr\fR(3X)
 468 setcchar/\fBcurs_getcchar\fR(3X)
 469 setscrreg/\fBcurs_outopts\fR(3X)
 470 setsyx/\fBcurs_kernel\fR(3X)
 471 setterm/\fBcurs_terminfo\fR(3X)
 472 setupterm/\fBcurs_terminfo\fR(3X)
 473 slk_attr/\fBcurs_slk\fR(3X)*
 474 slk_attr_off/\fBcurs_slk\fR(3X)
 475 slk_attr_on/\fBcurs_slk\fR(3X)
 476 slk_attr_set/\fBcurs_slk\fR(3X)
 477 slk_attroff/\fBcurs_slk\fR(3X)
 478 slk_attron/\fBcurs_slk\fR(3X)
 479 slk_attrset/\fBcurs_slk\fR(3X)
 480 slk_clear/\fBcurs_slk\fR(3X)
 481 slk_color/\fBcurs_slk\fR(3X)
 482 slk_init/\fBcurs_slk\fR(3X)
 483 slk_label/\fBcurs_slk\fR(3X)
 484 slk_noutrefresh/\fBcurs_slk\fR(3X)
 485 slk_refresh/\fBcurs_slk\fR(3X)
 486 slk_restore/\fBcurs_slk\fR(3X)
 487 slk_set/\fBcurs_slk\fR(3X)
 488 slk_touch/\fBcurs_slk\fR(3X)
 489 standend/\fBcurs_attr\fR(3X)
 490 standout/\fBcurs_attr\fR(3X)
 491 start_color/\fBcurs_color\fR(3X)
 492 subpad/\fBcurs_pad\fR(3X)
 493 subwin/\fBcurs_window\fR(3X)
 494 syncok/\fBcurs_window\fR(3X)
 495 term_attrs/\fBcurs_termattrs\fR(3X)
 496 termattrs/\fBcurs_termattrs\fR(3X)
 497 termname/\fBcurs_termattrs\fR(3X)
 498 tgetent/\fBcurs_termcap\fR(3X)
 499 tgetflag/\fBcurs_termcap\fR(3X)
 500 tgetnum/\fBcurs_termcap\fR(3X)
 501 tgetstr/\fBcurs_termcap\fR(3X)
 502 tgoto/\fBcurs_termcap\fR(3X)
 503 tigetflag/\fBcurs_terminfo\fR(3X)
 504 tigetnum/\fBcurs_terminfo\fR(3X)
 505 tigetstr/\fBcurs_terminfo\fR(3X)
 506 timeout/\fBcurs_inopts\fR(3X)
 507 touchline/\fBcurs_touch\fR(3X)
 508 touchwin/\fBcurs_touch\fR(3X)
 509 tparm/\fBcurs_terminfo\fR(3X)
 510 tputs/\fBcurs_termcap\fR(3X)
 511 tputs/\fBcurs_terminfo\fR(3X)
 512 trace/\fBcurs_trace\fR(3X)*
 513 typeahead/\fBcurs_inopts\fR(3X)
 514 unctrl/\fBcurs_util\fR(3X)
 515 unget_wch/\fBcurs_get_wch\fR(3X)
 516 ungetch/\fBcurs_getch\fR(3X)
 517 ungetmouse/\fBcurs_mouse\fR(3X)*
 518 untouchwin/\fBcurs_touch\fR(3X)
 519 use_default_colors/\fBdefault_colors\fR(3X)*
 520 use_env/\fBcurs_util\fR(3X)
 521 use_extended_names/\fBcurs_extend\fR(3X)*
 522 vid_attr/\fBcurs_terminfo\fR(3X)
 523 vid_puts/\fBcurs_terminfo\fR(3X)
 524 vidattr/\fBcurs_terminfo\fR(3X)
 525 vidputs/\fBcurs_terminfo\fR(3X)
 526 vline/\fBcurs_border\fR(3X)
 527 vline_set/\fBcurs_border_set\fR(3X)
 528 vw_printw/\fBcurs_printw\fR(3X)
 529 vw_scanw/\fBcurs_scanw\fR(3X)
 530 vwprintw/\fBcurs_printw\fR(3X)
 531 vwscanw/\fBcurs_scanw\fR(3X)
 532 wadd_wch/\fBcurs_add_wch\fR(3X)
 533 wadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
 534 wadd_wchstr/\fBcurs_add_wchstr\fR(3X)
 535 waddch/\fBcurs_addch\fR(3X)
 536 waddchnstr/\fBcurs_addchstr\fR(3X)
 537 waddchstr/\fBcurs_addchstr\fR(3X)
 538 waddnstr/\fBcurs_addstr\fR(3X)
 539 waddnwstr/\fBcurs_addwstr\fR(3X)
 540 waddstr/\fBcurs_addstr\fR(3X)
 541 waddwstr/\fBcurs_addwstr\fR(3X)
 542 wattr_get/\fBcurs_attr\fR(3X)
 543 wattr_off/\fBcurs_attr\fR(3X)
 544 wattr_on/\fBcurs_attr\fR(3X)
 545 wattr_set/\fBcurs_attr\fR(3X)
 546 wattroff/\fBcurs_attr\fR(3X)
 547 wattron/\fBcurs_attr\fR(3X)
 548 wattrset/\fBcurs_attr\fR(3X)
 549 wbkgd/\fBcurs_bkgd\fR(3X)
 550 wbkgdset/\fBcurs_bkgd\fR(3X)
 551 wbkgrnd/\fBcurs_bkgrnd\fR(3X)
 552 wbkgrndset/\fBcurs_bkgrnd\fR(3X)
 553 wborder/\fBcurs_border\fR(3X)
 554 wborder_set/\fBcurs_border_set\fR(3X)
 555 wchgat/\fBcurs_attr\fR(3X)
 556 wclear/\fBcurs_clear\fR(3X)
 557 wclrtobot/\fBcurs_clear\fR(3X)
 558 wclrtoeol/\fBcurs_clear\fR(3X)
 559 wcolor_set/\fBcurs_attr\fR(3X)
 560 wcursyncup/\fBcurs_window\fR(3X)
 561 wdelch/\fBcurs_delch\fR(3X)
 562 wdeleteln/\fBcurs_deleteln\fR(3X)
 563 wecho_wchar/\fBcurs_add_wch\fR(3X)
 564 wechochar/\fBcurs_addch\fR(3X)
 565 wenclose/\fBcurs_mouse\fR(3X)*
 566 werase/\fBcurs_clear\fR(3X)
 567 wget_wch/\fBcurs_get_wch\fR(3X)
 568 wget_wstr/\fBcurs_get_wstr\fR(3X)
 569 wgetbkgrnd/\fBcurs_bkgrnd\fR(3X)
 570 wgetch/\fBcurs_getch\fR(3X)
 571 wgetn_wstr/\fBcurs_get_wstr\fR(3X)
 572 wgetnstr/\fBcurs_getstr\fR(3X)
 573 wgetstr/\fBcurs_getstr\fR(3X)
 574 whline/\fBcurs_border\fR(3X)
 575 whline_set/\fBcurs_border_set\fR(3X)
 576 win_wch/\fBcurs_in_wch\fR(3X)
 577 win_wchnstr/\fBcurs_in_wchstr\fR(3X)
 578 win_wchstr/\fBcurs_in_wchstr\fR(3X)
 579 winch/\fBcurs_inch\fR(3X)
 580 winchnstr/\fBcurs_inchstr\fR(3X)
 581 winchstr/\fBcurs_inchstr\fR(3X)
 582 winnstr/\fBcurs_instr\fR(3X)
 583 winnwstr/\fBcurs_inwstr\fR(3X)
 584 wins_nwstr/\fBcurs_ins_wstr\fR(3X)
 585 wins_wch/\fBcurs_ins_wch\fR(3X)
 586 wins_wstr/\fBcurs_ins_wstr\fR(3X)
 587 winsch/\fBcurs_insch\fR(3X)
 588 winsdelln/\fBcurs_deleteln\fR(3X)
 589 winsertln/\fBcurs_deleteln\fR(3X)
 590 winsnstr/\fBcurs_insstr\fR(3X)
 591 winsstr/\fBcurs_insstr\fR(3X)
 592 winstr/\fBcurs_instr\fR(3X)
 593 winwstr/\fBcurs_inwstr\fR(3X)
 594 wmouse_trafo/\fBcurs_mouse\fR(3X)*
 595 wmove/\fBcurs_move\fR(3X)
 596 wnoutrefresh/\fBcurs_refresh\fR(3X)
 597 wprintw/\fBcurs_printw\fR(3X)
 598 wredrawln/\fBcurs_refresh\fR(3X)
 599 wrefresh/\fBcurs_refresh\fR(3X)
 600 wresize/\fBwresize\fR(3X)*
 601 wscanw/\fBcurs_scanw\fR(3X)
 602 wscrl/\fBcurs_scroll\fR(3X)
 603 wsetscrreg/\fBcurs_outopts\fR(3X)
 604 wstandend/\fBcurs_attr\fR(3X)
 605 wstandout/\fBcurs_attr\fR(3X)
 606 wsyncdown/\fBcurs_window\fR(3X)
 607 wsyncup/\fBcurs_window\fR(3X)
 608 wtimeout/\fBcurs_inopts\fR(3X)
 609 wtouchln/\fBcurs_touch\fR(3X)
 610 wunctrl/\fBcurs_util\fR(3X)
 611 wvline/\fBcurs_border\fR(3X)
 612 wvline_set/\fBcurs_border_set\fR(3X)
 613 .TE
 614 .SH RETURN VALUE
 615 Routines that return an integer return \fBERR\fR upon failure and an
 616 integer value other than \fBERR\fR upon successful completion, unless
 617 otherwise noted in the routine descriptions.
 618 .PP
 619 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
 620 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.  The return
 621 values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
 622 \fBgetmaxyx\fR are undefined (i.e., these should not be used as the
 623 right-hand side of assignment statements).
 624 .PP
 625 Routines that return pointers return \fBNULL\fR on error.
 626 .SH ENVIRONMENT
 627 The following environment symbols are useful for customizing the
 628 runtime behavior of the \fBncurses\fR library.  The most important
 629 ones have been already discussed in detail.
 630 .TP 5
 631 BAUDRATE
 632 The debugging library checks this environment symbol when the application
 633 has redirected output to a file.
 634 The symbol's numeric value is used for the baudrate.
 635 If no value is found, \fBncurses\fR uses 9600.
 636 This allows testers to construct repeatable test-cases
 637 that take into account costs that depend on baudrate.
 638 .TP 5
 639 CC
 640 When set, change occurrences of the command_character
 641 (i.e., the \fBcmdch\fP capability)
 642 of the loaded terminfo entries to the value of this symbol.
 643 Very few terminfo entries provide this feature.
 644 .TP 5
 645 COLUMNS
 646 Specify the width of the screen in characters.
 647 Applications running in a windowing environment usually are able to
 648 obtain the width of the window in which they are executing.
 649 If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available,
 650 \fBncurses\fR uses the size which may be specified in the terminfo database
 651 (i.e., the \fBcols\fR capability).
 652 .IP
 653 It is important that your application use a correct size for the screen.
 654 This is not always possible because your application may be
 655 running on a host which does not honor NAWS (Negotiations About Window
 656 Size), or because you are temporarily running as another user.
 657 However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
 658 use of the screen size obtained from the operating system.
 659 .IP
 660 Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently.
 661 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
 662 e.g., xterm which commonly specifies a 65 line screen.
 663 For best results, \fBlines\fR and \fBcols\fR should not be specified in
 664 a terminal description for terminals which are run as emulations.
 665 .IP
 666 Use the \fBuse_env\fR function to disable all use of external environment
 667 (including system calls) to determine the screen size.
 668 .TP 5
 669 ESCDELAY
 670 Specifies the total time, in milliseconds, for which ncurses will
 671 await a character sequence, e.g., a function key.
 672 The default value, 1000 milliseconds, is enough for most uses.
 673 However, it is made a variable to accommodate unusual applications.
 674 .IP
 675 The most common instance where you may wish to change this value
 676 is to work with slow hosts, e.g., running on a network.
 677 If the host cannot read characters rapidly enough, it will have the same
 678 effect as if the terminal did not send characters rapidly enough.
 679 The library will still see a timeout.
 680 .IP
 681 Note that xterm mouse events are built up from character sequences
 682 received from the xterm.
 683 If your application makes heavy use of multiple-clicking, you may
 684 wish to lengthen this default value because the timeout applies
 685 to the composed multi-click event as well as the individual clicks.
 686 .IP
 687 In addition to the environment variable,
 688 this implementation provides a global variable with the same name.
 689 Portable applications should not rely upon the presence of ESCDELAY
 690 in either form,
 691 but setting the environment variable rather than the global variable
 692 does not create problems when compiling an application.
 693 .TP 5
 694 HOME
 695 Tells \fBncurses\fR where your home directory is.
 696 That is where it may read and write auxiliary terminal descriptions:
 697 .IP
 698 $HOME/.termcap
 699 .br
 700 $HOME/.terminfo
 701 .TP 5
 702 LINES
 703 Like COLUMNS, specify the height of the screen in characters.
 704 See COLUMNS for a detailed description.
 705 .TP 5
 706 MOUSE_BUTTONS_123
 707 This applies only to the OS/2 EMX port.
 708 It specifies the order of buttons on the mouse.
 709 OS/2 numbers a 3-button mouse inconsistently from other
 710 platforms:
 711 .sp
 712 1 = left
 713 .br
 714 2 = right
 715 .br
 716 3 = middle.
 717 .sp
 718 This symbol lets you customize the mouse.
 719 The symbol must be three numeric digits 1-3 in any order, e.g., 123 or 321.
 720 If it is not specified, \fBncurses\fR uses 132.
 721 .TP 5
 722 NCURSES_ASSUMED_COLORS
 723 Override the compiled-in assumption that the
 724 terminal's default colors are white-on-black
 725 (see \fBdefault_colors\fR(3X)).
 726 You may set the foreground and background color values with this environment
 727 variable by proving a 2-element list: foreground,background.
 728 For example, to tell ncurses to not assume anything
 729 about the colors, set this to "-1,-1".
 730 To make it green-on-black, set it to "2,0".
 731 Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
 732 .TP 5
 733 NCURSES_NO_HARD_TABS
 734 \fBNcurses\fP may use tabs as part of the cursor movement optimization.
 735 In some cases,
 736 your terminal driver may not handle these properly.
 737 Set this environment variable to disable the feature.
 738 You can also adjust your \fBstty\fP settings to avoid the problem.
 739 .TP 5
 740 NCURSES_NO_MAGIC_COOKIES
 741 Some terminals use a magic-cookie feature which requires special handling
 742 to make highlighting and other video attributes display properly.
 743 You can suppress the highlighting entirely for these terminals by
 744 setting this environment variable.
 745 .TP 5
 746 NCURSES_NO_PADDING
 747 Most of the terminal descriptions in the terminfo database are written
 748 for real "hardware" terminals.
 749 Many people use terminal emulators
 750 which run in a windowing environment and use curses-based applications.
 751 Terminal emulators can duplicate
 752 all of the important aspects of a hardware terminal, but they do not
 753 have the same limitations.
 754 The chief limitation of a hardware terminal from the standpoint
 755 of your application is the management of dataflow, i.e., timing.
 756 Unless a hardware terminal is interfaced into a terminal concentrator
 757 (which does flow control),
 758 it (or your application) must manage dataflow, preventing overruns.
 759 The cheapest solution (no hardware cost)
 760 is for your program to do this by pausing after
 761 operations that the terminal does slowly, such as clearing the display.
 762 .IP
 763 As a result, many terminal descriptions (including the vt100)
 764 have delay times embedded.  You may wish to use these descriptions,
 765 but not want to pay the performance penalty.
 766 .IP
 767 Set the NCURSES_NO_PADDING symbol to disable all but mandatory
 768 padding.  Mandatory padding is used as a part of special control
 769 sequences such as \fIflash\fR.
 770 .TP 5
 771 NCURSES_NO_SETBUF
 772 Normally \fBncurses\fR enables buffered output during terminal initialization.
 773 This is done (as in SVr4 curses) for performance reasons.
 774 For testing purposes, both of \fBncurses\fR and certain applications,
 775 this feature is made optional.  Setting the NCURSES_NO_SETBUF variable
 776 disables output buffering, leaving the output in the original (usually
 777 line buffered) mode.
 778 .TP 5
 779 NCURSES_NO_UTF8_ACS
 780 During initialization, the \fBncurses\fR library
 781 checks for special cases where VT100 line-drawing (and the corresponding
 782 alternate character set capabilities) described in the terminfo are known
 783 to be missing.
 784 Specifically, when running in a UTF-8 locale,
 785 the Linux console emulator and the GNU screen program ignore these.
 786 Ncurses checks the TERM environment variable for these.
 787 For other special cases, you should set this environment variable.
 788 Doing this tells ncurses to use Unicode values which correspond to
 789 the VT100 line-drawing glyphs.
 790 That works for the special cases cited,
 791 and is likely to work for terminal emulators.
 792 .IP
 793 When setting this variable, you should set it to a nonzero value.
 794 Setting it to zero (or to a nonnumber)
 795 disables the special check for Linux and screen.
 796 .TP 5
 797 NCURSES_TRACE
 798 During initialization, the \fBncurses\fR debugging library
 799 checks the NCURSES_TRACE symbol.
 800 If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
 801 function, using that value as the argument.
 802 .IP
 803 The argument values, which are defined in \fBcurses.h\fR, provide several
 804 types of information.
 805 When running with traces enabled, your application will write the
 806 file \fBtrace\fR to the current directory.
 807 .TP 5
 808 TERM
 809 Denotes your terminal type.
 810 Each terminal type is distinct, though many are similar.
 811 .TP 5
 812 TERMCAP
 813 If the \fBncurses\fR library has been configured with \fItermcap\fR
 814 support, \fBncurses\fR will check for a terminal's description in
 815 termcap form if it is not available in the terminfo database.
 816 .IP
 817 The TERMCAP symbol contains either a terminal description (with
 818 newlines stripped out),
 819 or a file name telling where the information denoted by the TERM symbol exists.
 820 In either case, setting it directs \fBncurses\fR to ignore
 821 the usual place for this information, e.g., /etc/termcap.
 822 .TP 5
 823 TERMINFO
 824 Overrides the directory in which \fBncurses\fR searches for your terminal
 825 description.
 826 This is the simplest, but not the only way to change the list of directories.
 827 The complete list of directories in order follows:
 828 .RS
 829 .TP 3
 830 -
 831 the last directory to which \fBncurses\fR wrote, if any, is searched first
 832 .TP 3
 833 -
 834 the directory specified by the TERMINFO symbol
 835 .TP 3
 836 -
 837 $HOME/.terminfo
 838 .TP 3
 839 -
 840 directories listed in the TERMINFO_DIRS symbol
 841 .TP 3
 842 -
 843 one or more directories whose names are configured and compiled into the
 844 ncurses library, e.g.,
 845 @TERMINFO@
 846 .RE
 847 .TP 5
 848 TERMINFO_DIRS
 849 Specifies a list of directories to search for terminal descriptions.
 850 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
 851 All of the terminal descriptions are in terminfo form, which makes
 852 a subdirectory named for the first letter of the terminal names therein.
 853 .TP 5
 854 TERMPATH
 855 If TERMCAP does not hold a file name then \fBncurses\fR checks
 856 the TERMPATH symbol.
 857 This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
 858 If the TERMPATH symbol is not set, \fBncurses\fR looks in the files
 859 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
 860 .PP
 861 The library may be configured to disregard the following variables when the
 862 current user is the superuser (root), or if the application uses setuid or
 863 setgid permissions:
 864 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
 865 .SH ALTERNATE CONFIGURATIONS
 866 Several different configurations are possible,
 867 depending on the configure script options used when building \fBncurses\fP.
 868 There are a few main options whose effects are visible to the applications
 869 developer using \fBncurses\fP:
 870 .TP 5
 871 --disable-overwrite
 872 The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
 873 .RS
 874 .sp
 875 \fB#include <curses.h>\fR
 876 .RE
 877 .IP
 878 This option is used to avoid filename conflicts when \fBncurses\fP
 879 is not the main implementation of curses of the computer.
 880 If \fBncurses\fP is installed disabling overwrite, it puts its headers in
 881 a subdirectory, e.g.,
 882 .RS
 883 .sp
 884 \fB#include <ncurses/curses.h>\fR
 885 .RE
 886 .IP
 887 It also omits a symbolic link which would allow you to use \fB-lcurses\fP
 888 to build executables.
 889 .TP 5
 890 --enable-widec
 891 The configure script renames the library and (if the \fB--disable-overwrite\fP
 892 option is used) puts the header files in a different subdirectory.
 893 All of the library names have a "w" appended to them,
 894 i.e., instead of
 895 .RS
 896 .sp
 897 \fB-lncurses\fR
 898 .RE
 899 .IP
 900 you link with
 901 .RS
 902 .sp
 903 \fB-lncursesw\fR
 904 .RE
 905 .IP
 906 You must also define \fB_XOPEN_SOURCE_EXTENDED\fP when compiling for the
 907 wide-character library to use the extended (wide-character) functions.
 908 The \fBcurses.h\fP file which is installed for the wide-character
 909 library is designed to be compatible with the normal library's header.
 910 Only the size of the \fBWINDOW\fP structure differs, and very few
 911 applications require more than a pointer to \fBWINDOW\fPs.
 912 If the headers are installed allowing overwrite,
 913 the wide-character library's headers should be installed last,
 914 to allow applications to be built using either library
 915 from the same set of headers.
 916 .TP 5
 917 --with-shared
 918 .TP
 919 --with-normal
 920 .TP
 921 --with-debug
 922 .TP
 923 --with-profile
 924 The shared and normal (static) library names differ by their suffixes,
 925 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
 926 The debug and profiling libraries add a "_g" and a "_p" to the root
 927 names respectively,
 928 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
 929 .TP 5
 930 --with-trace
 931 The \fBtrace\fP function normally resides in the debug library,
 932 but it is sometimes useful to configure this in the shared library.
 933 Configure scripts should check for the function's existence rather
 934 than assuming it is always in the debug library.
 935 .SH FILES
 936 .TP 5
 937 @DATADIR@/tabset
 938 directory containing initialization files for the terminal capability database
 939 @TERMINFO@
 940 terminal capability database
 941 .SH SEE ALSO
 942 \fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine
 943 descriptions.
 944 .SH EXTENSIONS
 945 The \fBncurses\fR library can be compiled with an option (\fB-DUSE_GETCAP\fR)
 946 that falls back to the old-style /etc/termcap file if the terminal setup code
 947 cannot find a terminfo entry corresponding to \fBTERM\fR.  Use of this feature
 948 is not recommended, as it essentially includes an entire termcap compiler in
 949 the \fBncurses\fR startup code, at significant cost in core and startup cycles.
 950 .PP
 951 The \fBncurses\fR library includes facilities for capturing mouse events on
 952 certain terminals (including xterm). See the \fBcurs_mouse\fR(3X)
 953 manual page for details.
 954 .PP
 955 The \fBncurses\fR library includes facilities for responding to window
 956 resizing events, e.g., when running in an xterm.
 957 See the \fBresizeterm\fR(3X)
 958 and \fBwresize\fR(3X) manual pages for details.
 959 In addition, the library may be configured with a SIGWINCH handler.
 960 .PP
 961 The \fBncurses\fR library extends the fixed set of function key capabilities
 962 of terminals by allowing the application designer to define additional
 963 key sequences at runtime.
 964 See the \fBdefine_key\fR(3X)
 965 \fBkey_defined\fR(3X),
 966 and \fBkeyok\fR(3X) manual pages for details.
 967 .PP
 968 The \fBncurses\fR library can exploit the capabilities of terminals which
 969 implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an application
 970 to reset the terminal to its original foreground and background colors.
 971 From the users' perspective, the application is able to draw colored
 972 text on a background whose color is set independently, providing better
 973 control over color contrasts.
 974 See the \fBdefault_colors\fR(3X) manual page for details.
 975 .PP
 976 The \fBncurses\fR library includes a function for directing application output
 977 to a printer attached to the terminal device.  See the \fBcurs_print\fR(3X)
 978 manual page for details.
 979 .SH PORTABILITY
 980 The \fBncurses\fR library is intended to be BASE-level conformant with the XSI
 981 Curses standard.  The EXTENDED XSI Curses functionality
 982 (including color support) is supported.
 983 .PP
 984 A small number of local differences (that is, individual differences between
 985 the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
 986 sections of the library man pages.
 987 .PP
 988 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.  See
 989 the \fBcurs_getch\fR(3X) manual page for details.
 990 .PP
 991 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.  See
 992 the \fBcurs_slk\fR(3X) manual page for details.
 993 .PP
 994 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
 995 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
 996 part of XPG4, nor are they present in SVr4.  See the \fBcurs_mouse\fR(3X)
 997 manual page for details.
 998 .PP
 999 The routine \fBmcprint\fR was not present in any previous curses
1000 implementation.  See the \fBcurs_print\fR(3X) manual page for details.
1001 .PP
1002 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.  See
1003 the \fBwresize\fR(3X) manual page for details.
1004 .PP
1005 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
1006 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
1007 bits in the UNIX tty driver.  In this implementation, all padding is done by
1008 NUL sends.  This method is slightly more expensive, but narrows the interface
1009 to the UNIX kernel significantly and increases the package's portability
1010 correspondingly.
1011 .SH NOTES
1012 The header file \fB<curses.h>\fR automatically includes the header files
1013 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
1014 .PP
1015 If standard output from a \fBncurses\fR program is re-directed to something
1016 which is not a tty, screen updates will be directed to standard error.  This
1017 was an undocumented feature of AT&T System V Release 3 curses.
1018 .SH AUTHORS
1019 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1020 Based on pcurses by Pavel Curtis.
1021 .\"#
1022 .\"# The following sets edit modes for GNU EMACS
1023 .\"# Local Variables:
1024 .\"# mode:nroff
1025 .\"# fill-column:79
1026 .\"# End: