man/ncurses.3x

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright (c) 1998,1999 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.35 1999/10/23 19:50:07 tom Exp $
  31 .hy 0
  32 .TH ncurses 3X ""
  33 .ds n 5
  34 .ds d @DATADIR@/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
  46 The \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System V
  47 Release 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fR
  48 library is freely redistributable in source form.  Differences from the SVr4
  49 curses are summarized under the EXTENSIONS and BUGS sections below and
  50 described in detail in the EXTENSIONS and BUGS sections of individual man
  51 pages.
  52
  53 A program using these routines must be linked with the \fB-lncurses\fR option,
  54 or (if it has been generated) with the debugging library \fB-lncurses_g\fR.
  55 (Your system integrator may also have installed these libraries under
  56 the names \fB-lcurses\fR and \fB-lcurses_g\fR.)
  57 The ncurses_g library generates trace logs (in a file called 'trace' in the
  58 current directory) that describe curses actions.
  59
  60 The \fBncurses\fR package supports: overall screen, window and pad
  61 manipulation; output to windows and pads; reading terminal input; control over
  62 terminal and \fBcurses\fR input and output options; environment query
  63 routines; color manipulation; use of soft label keys; terminfo capabilities;
  64 and access to low-level terminal-manipulation routines.
  65
  66 To initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fR
  67 must be called before any of the other routines that deal with windows
  68 and screens are used.  The routine \fBendwin\fR must be called before
  69 exiting.  To get character-at-a-time input without echoing (most
  70 interactive, screen oriented programs want this), the following
  71 sequence should be used:
  72
  73       \fBinitscr(); cbreak(); noecho();\fR
  74
  75 Most programs would additionally use the sequence:
  76
  77       \fBnonl();\fR
  78       \fBintrflush(stdscr, FALSE);\fR
  79       \fBkeypad(stdscr, TRUE);\fR
  80
  81 Before a \fBcurses\fR program is run, the tab stops of the terminal
  82 should be set and its initialization strings, if defined, must be
  83 output.  This can be done by executing the \fBtput init\fR command
  84 after the shell environment variable \fBTERM\fR has been exported.
  85 \fBtset(1)\fR is usually responsible for doing this.
  86 [See \fBterminfo\fR(\*n) for further details.]
  87
  88 The \fBncurses\fR library permits manipulation of data structures,
  89 called \fIwindows\fR, which can be thought of as two-dimensional
  90 arrays of characters representing all or part of a CRT screen.  A
  91 default window called \fBstdscr\fR, which is the size of the terminal
  92 screen, is supplied.  Others may be created with \fBnewwin\fR.
  93
  94 Note that \fBcurses\fR does not handle overlapping windows, that's done by
  95 the \fBpanel\fR(3X) library. This means that you can either use
  96 \fBstdscr\fR or divide the screen into tiled windows and not using
  97 \fBstdscr\fR at all. Mixing the two will result in unpredictable, and
  98 undesired, effects.
  99
 100 Windows are referred to by variables declared as \fBWINDOW *\fR.
 101 These data structures are manipulated with routines described here and
 102 elsewhere in the \fBncurses\fR manual pages.  Among which the most basic
 103 routines are \fBmove\fR and \fBaddch\fR.  More general versions of
 104 these routines are included with names beginning with \fBw\fR,
 105 allowing the user to specify a window.  The routines not beginning
 106 with \fBw\fR affect \fBstdscr\fR.)
 107
 108 After using routines to manipulate a window, \fBrefresh\fR is called,
 109 telling \fBcurses\fR to make the user's CRT screen look like
 110 \fBstdscr\fR.  The characters in a window are actually of type
 111 \fBchtype\fR, (character and attribute data) so that other information
 112 about the character may also be stored with each character.
 113
 114 Special windows called \fIpads\fR may also be manipulated.  These are windows
 115 which are not constrained to the size of the screen and whose contents need not
 116 be completely displayed.  See \fBcurs_pad\fR(3X) for more information.
 117
 118 In addition to drawing characters on the screen, video attributes and colors
 119 may be supported, causing the characters to show up in such modes as
 120 underlined, in reverse video, or in color on terminals that support such
 121 display enhancements.  Line drawing characters may be specified to be output.
 122 On input, \fBcurses\fR is also able to translate arrow and function keys that
 123 transmit escape sequences into single values.  The video attributes, line
 124 drawing characters, and input values use names, defined in \fB<curses.h>\fR,
 125 such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
 126
 127 If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
 128 program is executing in a window environment, line and column information in
 129 the environment will override information read by \fIterminfo\fR.  This would
 130 effect a program running in an AT&T 630 layer, for example, where the size of a
 131 screen is changeable (see \fBENVIRONMENT\fR).
 132
 133 If the environment variable \fBTERMINFO\fR is defined, any program using
 134 \fBcurses\fR checks for a local terminal definition before checking in the
 135 standard place.  For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
 136 compiled terminal definition is found in
 137
 138       \fB\*d/a/att4424\fR.
 139
 140 (The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
 141 creation of huge directories.)  However, if \fBTERMINFO\fR is set to
 142 \fB$HOME/myterms\fR, \fBcurses\fR first checks
 143
 144       \fB$HOME/myterms/a/att4424\fR,
 145
 146 and if that fails, it then checks
 147
 148       \fB\*d/a/att4424\fR.
 149
 150 This is useful for developing experimental definitions or when write
 151 permission in \fB\*d\fR is not available.
 152
 153 The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
 154 \fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
 155 screen.  The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
 156 \fB0\fR, respectively.
 157
 158 The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
 159 which is used for certain low-level operations like clearing and redrawing a
 160 screen containing garbage.  The \fBcurscr\fR can be used in only a few
 161 routines.
 162
 163 .SS Routine and Argument Names
 164 Many \fBcurses\fR routines have two or more versions.  The routines prefixed
 165 with \fBw\fR require a window argument.  The routines prefixed with \fBp\fR
 166 require a pad argument.  Those without a prefix generally use \fBstdscr\fR.
 167
 168 The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
 169 coordinate to move to before performing the appropriate action.  The
 170 \fBmv\fR routines imply a call to \fBmove\fR before the call to the
 171 other routine.  The coordinate \fIy\fR always refers to the row (of
 172 the window), and \fIx\fR always refers to the column.  The upper
 173 left-hand corner is always (0,0), not (1,1).
 174
 175 The routines prefixed with \fBmvw\fR take both a window argument and
 176 \fIx\fR and \fIy\fR coordinates.  The window argument is always
 177 specified before the coordinates.
 178
 179 In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
 180 pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
 181 \fBWINDOW\fR.
 182
 183 Option setting routines require a Boolean flag \fIbf\fR with the value
 184 \fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.  The
 185 variables \fIch\fR and \fIattrs\fR below are always of type
 186 \fBchtype\fR.  The types \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and
 187 \fBchtype\fR are defined in \fB<curses.h>\fR.  The type \fBTERMINAL\fR
 188 is defined in \fB<term.h>\fR.  All other arguments are integers.
 189
 190 .SS Routine Name Index
 191 The following table lists each \fBcurses\fR routine and the name of
 192 the manual page on which it is described.  Routines flagged with `*'
 193 are ncurses-specific, not described by XPG4 or present in SVr4.
 194
 195 .TS
 196 center tab(/);
 197 l l
 198 l l .
 199 \fBcurses\fR Routine Name/Manual Page Name
 200 =
 201 addch/\fBcurs_addch\fR(3X)
 202 addchnstr/\fBcurs_addchstr\fR(3X)
 203 addchstr/\fBcurs_addchstr\fR(3X)
 204 addnstr/\fBcurs_addstr\fR(3X)
 205 addstr/\fBcurs_addstr\fR(3X)
 206 attr_get/\fBcurs_attr\fR(3X)
 207 attr_off/\fBcurs_attr\fR(3X)
 208 attr_on/\fBcurs_attr\fR(3X)
 209 attr_set/\fBcurs_attr\fR(3X)
 210 attroff/\fBcurs_attr\fR(3X)
 211 attron/\fBcurs_attr\fR(3X)
 212 attrset/\fBcurs_attr\fR(3X)
 213 baudrate/\fBcurs_termattrs\fR(3X)
 214 beep/\fBcurs_beep\fR(3X)
 215 bkgd/\fBcurs_bkgd\fR(3X)
 216 bkgdset/\fBcurs_bkgd\fR(3X)
 217 border/\fBcurs_border\fR(3X)
 218 box/\fBcurs_border\fR(3X)
 219 can_change_color/\fBcurs_color\fR(3X)
 220 cbreak/\fBcurs_inopts\fR(3X)
 221 chgat/\fBcurs_attr\fR(3X)
 222 clear/\fBcurs_clear\fR(3X)
 223 clearok/\fBcurs_outopts\fR(3X)
 224 clrtobot/\fBcurs_clear\fR(3X)
 225 clrtoeol/\fBcurs_clear\fR(3X)
 226 color_content/\fBcurs_color\fR(3X)
 227 color_set/\fBcurs_attr\fR(3X)
 228 copywin/\fBcurs_overlay\fR(3X)
 229 curs_set/\fBcurs_kernel\fR(3X)
 230 def_prog_mode/\fBcurs_kernel\fR(3X)
 231 def_shell_mode/\fBcurs_kernel\fR(3X)
 232 define_key/\fBdefine_key\fR(3X)*
 233 del_curterm/\fBcurs_terminfo\fR(3X)
 234 delay_output/\fBcurs_util\fR(3X)
 235 delch/\fBcurs_delch\fR(3X)
 236 deleteln/\fBcurs_deleteln\fR(3X)
 237 delscreen/\fBcurs_initscr\fR(3X)
 238 delwin/\fBcurs_window\fR(3X)
 239 derwin/\fBcurs_window\fR(3X)
 240 doupdate/\fBcurs_refresh\fR(3X)
 241 dupwin/\fBcurs_window\fR(3X)
 242 echo/\fBcurs_inopts\fR(3X)
 243 echochar/\fBcurs_addch\fR(3X)
 244 endwin/\fBcurs_initscr\fR(3X)
 245 erase/\fBcurs_clear\fR(3X)
 246 erasechar/\fBcurs_termattrs\fR(3X)
 247 filter/\fBcurs_util\fR(3X)
 248 flash/\fBcurs_beep\fR(3X)
 249 flushinp/\fBcurs_util\fR(3X)
 250 getbegyx/\fBcurs_getyx\fR(3X)
 251 getbkgd/\fBcurs_bkgd\fR(3X)
 252 getch/\fBcurs_getch\fR(3X)
 253 getmaxyx/\fBcurs_getyx\fR(3X)
 254 getmouse/\fBcurs_mouse\fR(3X)*
 255 getnstr/\fBcurs_getstr\fR(3X)
 256 getparyx/\fBcurs_getyx\fR(3X)
 257 getstr/\fBcurs_getstr\fR(3X)
 258 getsyx/\fBcurs_kernel\fR(3X)
 259 getwin/\fBcurs_util\fR(3X)
 260 getyx/\fBcurs_getyx\fR(3X)
 261 halfdelay/\fBcurs_inopts\fR(3X)
 262 has_colors/\fBcurs_color\fR(3X)
 263 has_ic/\fBcurs_termattrs\fR(3X)
 264 has_il/\fBcurs_termattrs\fR(3X)
 265 has_key/\fBcurs_getch\fR(3X)*
 266 hline/\fBcurs_border\fR(3X)
 267 idcok/\fBcurs_outopts\fR(3X)
 268 idlok/\fBcurs_outopts\fR(3X)
 269 immedok/\fBcurs_outopts\fR(3X)
 270 inch/\fBcurs_inch\fR(3X)
 271 inchnstr/\fBcurs_inchstr\fR(3X)
 272 inchstr/\fBcurs_inchstr\fR(3X)
 273 init_color/\fBcurs_color\fR(3X)
 274 init_pair/\fBcurs_color\fR(3X)
 275 initscr/\fBcurs_initscr\fR(3X)
 276 innstr/\fBcurs_instr\fR(3X)
 277 insch/\fBcurs_insch\fR(3X)
 278 insdelln/\fBcurs_deleteln\fR(3X)
 279 insertln/\fBcurs_deleteln\fR(3X)
 280 insnstr/\fBcurs_insstr\fR(3X)
 281 insstr/\fBcurs_insstr\fR(3X)
 282 instr/\fBcurs_instr\fR(3X)
 283 intrflush/\fBcurs_inopts\fR(3X)
 284 is_linetouched/\fBcurs_touch\fR(3X)
 285 is_wintouched/\fBcurs_touch\fR(3X)
 286 isendwin/\fBcurs_initscr\fR(3X)
 287 keyname/\fBcurs_util\fR(3X)
 288 keyok/\fBkeyok\fR(3X)*
 289 keypad/\fBcurs_inopts\fR(3X)
 290 killchar/\fBcurs_termattrs\fR(3X)
 291 leaveok/\fBcurs_outopts\fR(3X)
 292 longname/\fBcurs_termattrs\fR(3X)
 293 mcprint/\fBcurs_print\fR(3X)*
 294 meta/\fBcurs_inopts\fR(3X)
 295 mouseinterval/\fBcurs_mouse\fR(3X)*
 296 mousemask/\fBcurs_mouse\fR(3X)*
 297 move/\fBcurs_move\fR(3X)
 298 mvaddch/\fBcurs_addch\fR(3X)
 299 mvaddchnstr/\fBcurs_addchstr\fR(3X)
 300 mvaddchstr/\fBcurs_addchstr\fR(3X)
 301 mvaddnstr/\fBcurs_addstr\fR(3X)
 302 mvaddstr/\fBcurs_addstr\fR(3X)
 303 mvchgat/\fBcurs_attr\fR(3X)
 304 mvcur/\fBcurs_terminfo\fR(3X)
 305 mvdelch/\fBcurs_delch\fR(3X)
 306 mvderwin/\fBcurs_window\fR(3X)
 307 mvgetch/\fBcurs_getch\fR(3X)
 308 mvgetnstr/\fBcurs_getstr\fR(3X)
 309 mvgetstr/\fBcurs_getstr\fR(3X)
 310 mvhline/\fBcurs_border\fR(3X)
 311 mvinch/\fBcurs_inch\fR(3X)
 312 mvinchnstr/\fBcurs_inchstr\fR(3X)
 313 mvinchstr/\fBcurs_inchstr\fR(3X)
 314 mvinnstr/\fBcurs_instr\fR(3X)
 315 mvinsch/\fBcurs_insch\fR(3X)
 316 mvinsnstr/\fBcurs_insstr\fR(3X)
 317 mvinsstr/\fBcurs_insstr\fR(3X)
 318 mvinstr/\fBcurs_instr\fR(3X)
 319 mvprintw/\fBcurs_printw\fR(3X)
 320 mvscanw/\fBcurs_scanw\fR(3X)
 321 mvwaddch/\fBcurs_addch\fR(3X)
 322 mvwaddchnstr/\fBcurs_addchstr\fR(3X)
 323 mvwaddchstr/\fBcurs_addchstr\fR(3X)
 324 mvwaddnstr/\fBcurs_addstr\fR(3X)
 325 mvwaddstr/\fBcurs_addstr\fR(3X)
 326 mvwchgat/\fBcurs_attr\fR(3X)
 327 mvwdelch/\fBcurs_delch\fR(3X)
 328 mvwgetch/\fBcurs_getch\fR(3X)
 329 mvwgetnstr/\fBcurs_getstr\fR(3X)
 330 mvwgetstr/\fBcurs_getstr\fR(3X)
 331 mvwhline/\fBcurs_border\fR(3X)
 332 mvwin/\fBcurs_window\fR(3X)
 333 mvwinch/\fBcurs_inch\fR(3X)
 334 mvwinchnstr/\fBcurs_inchstr\fR(3X)
 335 mvwinchstr/\fBcurs_inchstr\fR(3X)
 336 mvwinnstr/\fBcurs_instr\fR(3X)
 337 mvwinsch/\fBcurs_insch\fR(3X)
 338 mvwinsnstr/\fBcurs_insstr\fR(3X)
 339 mvwinsstr/\fBcurs_insstr\fR(3X)
 340 mvwinstr/\fBcurs_instr\fR(3X)
 341 mvwprintw/\fBcurs_printw\fR(3X)
 342 mvwscanw/\fBcurs_scanw\fR(3X)
 343 mvwvline/\fBcurs_border\fR(3X)
 344 napms/\fBcurs_kernel\fR(3X)
 345 newpad/\fBcurs_pad\fR(3X)
 346 newterm/\fBcurs_initscr\fR(3X)
 347 newwin/\fBcurs_window\fR(3X)
 348 nl/\fBcurs_outopts\fR(3X)
 349 nocbreak/\fBcurs_inopts\fR(3X)
 350 nodelay/\fBcurs_inopts\fR(3X)
 351 noecho/\fBcurs_inopts\fR(3X)
 352 nonl/\fBcurs_outopts\fR(3X)
 353 noqiflush/\fBcurs_inopts\fR(3X)
 354 noraw/\fBcurs_inopts\fR(3X)
 355 notimeout/\fBcurs_inopts\fR(3X)
 356 overlay/\fBcurs_overlay\fR(3X)
 357 overwrite/\fBcurs_overlay\fR(3X)
 358 pair_content/\fBcurs_color\fR(3X)
 359 pechochar/\fBcurs_pad\fR(3X)
 360 pnoutrefresh/\fBcurs_pad\fR(3X)
 361 prefresh/\fBcurs_pad\fR(3X)
 362 printw/\fBcurs_printw\fR(3X)
 363 putp/\fBcurs_terminfo\fR(3X)
 364 putwin/\fBcurs_util\fR(3X)
 365 qiflush/\fBcurs_inopts\fR(3X)
 366 raw/\fBcurs_inopts\fR(3X)
 367 redrawwin/\fBcurs_refresh\fR(3X)
 368 refresh/\fBcurs_refresh\fR(3X)
 369 reset_prog_mode/\fBcurs_kernel\fR(3X)
 370 reset_shell_mode/\fBcurs_kernel\fR(3X)
 371 resetty/\fBcurs_kernel\fR(3X)
 372 resizeterm/\fBresizeterm\fR(3X)*
 373 restartterm/\fBcurs_terminfo\fR(3X)
 374 ripoffline/\fBcurs_kernel\fR(3X)
 375 savetty/\fBcurs_kernel\fR(3X)
 376 scanw/\fBcurs_scanw\fR(3X)
 377 scr_dump/\fBcurs_scr_dump\fR(3X)
 378 scr_init/\fBcurs_scr_dump\fR(3X)
 379 scr_restore/\fBcurs_scr_dump\fR(3X)
 380 scr_set/\fBcurs_scr_dump\fR(3X)
 381 scrl/\fBcurs_scroll\fR(3X)
 382 scroll/\fBcurs_scroll\fR(3X)
 383 scrollok/\fBcurs_outopts\fR(3X)
 384 set_curterm/\fBcurs_terminfo\fR(3X)
 385 set_term/\fBcurs_initscr\fR(3X)
 386 setscrreg/\fBcurs_outopts\fR(3X)
 387 setsyx/\fBcurs_kernel\fR(3X)
 388 setterm/\fBcurs_terminfo\fR(3X)
 389 setupterm/\fBcurs_terminfo\fR(3X)
 390 slk_attr/\fBcurs_slk\fR(3X)*
 391 slk_attr_off/\fBcurs_slk\fR(3X)
 392 slk_attr_on/\fBcurs_slk\fR(3X)
 393 slk_attr_set/\fBcurs_slk\fR(3X)
 394 slk_attroff/\fBcurs_slk\fR(3X)
 395 slk_attron/\fBcurs_slk\fR(3X)
 396 slk_attrset/\fBcurs_slk\fR(3X)
 397 slk_clear/\fBcurs_slk\fR(3X)
 398 slk_color/\fBcurs_slk\fR(3X)
 399 slk_init/\fBcurs_slk\fR(3X)
 400 slk_label/\fBcurs_slk\fR(3X)
 401 slk_noutrefresh/\fBcurs_slk\fR(3X)
 402 slk_refresh/\fBcurs_slk\fR(3X)
 403 slk_restore/\fBcurs_slk\fR(3X)
 404 slk_set/\fBcurs_slk\fR(3X)
 405 slk_touch/\fBcurs_slk\fR(3X)
 406 standend/\fBcurs_attr\fR(3X)
 407 standout/\fBcurs_attr\fR(3X)
 408 start_color/\fBcurs_color\fR(3X)
 409 subpad/\fBcurs_pad\fR(3X)
 410 subwin/\fBcurs_window\fR(3X)
 411 syncok/\fBcurs_window\fR(3X)
 412 termattrs/\fBcurs_termattrs\fR(3X)
 413 termname/\fBcurs_termattrs\fR(3X)
 414 tgetent/\fBcurs_termcap\fR(3X)
 415 tgetflag/\fBcurs_termcap\fR(3X)
 416 tgetnum/\fBcurs_termcap\fR(3X)
 417 tgetstr/\fBcurs_termcap\fR(3X)
 418 tgoto/\fBcurs_termcap\fR(3X)
 419 tigetflag/\fBcurs_terminfo\fR(3X)
 420 tigetnum/\fBcurs_terminfo\fR(3X)
 421 tigetstr/\fBcurs_terminfo\fR(3X)
 422 timeout/\fBcurs_inopts\fR(3X)
 423 touchline/\fBcurs_touch\fR(3X)
 424 touchwin/\fBcurs_touch\fR(3X)
 425 tparm/\fBcurs_terminfo\fR(3X)
 426 tputs/\fBcurs_termcap\fR(3X)
 427 tputs/\fBcurs_terminfo\fR(3X)
 428 typeahead/\fBcurs_inopts\fR(3X)
 429 unctrl/\fBcurs_util\fR(3X)
 430 ungetch/\fBcurs_getch\fR(3X)
 431 ungetmouse/\fBcurs_mouse\fR(3X)*
 432 untouchwin/\fBcurs_touch\fR(3X)
 433 use_default_colors/\fBdft_fgbg\fR(3X)*
 434 use_env/\fBcurs_util\fR(3X)
 435 vidattr/\fBcurs_terminfo\fR(3X)
 436 vidputs/\fBcurs_terminfo\fR(3X)
 437 vline/\fBcurs_border\fR(3X)
 438 vw_printw/\fBcurs_printw\fR(3X)
 439 vw_scanw/\fBcurs_scanw\fR(3X)
 440 vwprintw/\fBcurs_printw\fR(3X)
 441 vwscanw/\fBcurs_scanw\fR(3X)
 442 waddch/\fBcurs_addch\fR(3X)
 443 waddchnstr/\fBcurs_addchstr\fR(3X)
 444 waddchstr/\fBcurs_addchstr\fR(3X)
 445 waddnstr/\fBcurs_addstr\fR(3X)
 446 waddstr/\fBcurs_addstr\fR(3X)
 447 wattr_get/\fBcurs_attr\fR(3X)
 448 wattr_off/\fBcurs_attr\fR(3X)
 449 wattr_on/\fBcurs_attr\fR(3X)
 450 wattr_set/\fBcurs_attr\fR(3X)
 451 wattroff/\fBcurs_attr\fR(3X)
 452 wattron/\fBcurs_attr\fR(3X)
 453 wattrset/\fBcurs_attr\fR(3X)
 454 wbkgd/\fBcurs_bkgd\fR(3X)
 455 wbkgdset/\fBcurs_bkgd\fR(3X)
 456 wborder/\fBcurs_border\fR(3X)
 457 wchgat/\fBcurs_attr\fR(3X)
 458 wclear/\fBcurs_clear\fR(3X)
 459 wclrtobot/\fBcurs_clear\fR(3X)
 460 wclrtoeol/\fBcurs_clear\fR(3X)
 461 wcolor_set/\fBcurs_attr\fR(3X)
 462 wcursyncup/\fBcurs_window\fR(3X)
 463 wdelch/\fBcurs_delch\fR(3X)
 464 wdeleteln/\fBcurs_deleteln\fR(3X)
 465 wechochar/\fBcurs_addch\fR(3X)
 466 wenclose/\fBcurs_mouse\fR(3X)*
 467 werase/\fBcurs_clear\fR(3X)
 468 wgetch/\fBcurs_getch\fR(3X)
 469 wgetnstr/\fBcurs_getstr\fR(3X)
 470 wgetstr/\fBcurs_getstr\fR(3X)
 471 whline/\fBcurs_border\fR(3X)
 472 winch/\fBcurs_inch\fR(3X)
 473 winchnstr/\fBcurs_inchstr\fR(3X)
 474 winchstr/\fBcurs_inchstr\fR(3X)
 475 winnstr/\fBcurs_instr\fR(3X)
 476 winsch/\fBcurs_insch\fR(3X)
 477 winsdelln/\fBcurs_deleteln\fR(3X)
 478 winsertln/\fBcurs_deleteln\fR(3X)
 479 winsnstr/\fBcurs_insstr\fR(3X)
 480 winsstr/\fBcurs_insstr\fR(3X)
 481 winstr/\fBcurs_instr\fR(3X)
 482 wmouse_trafo/\fBcurs_mouse\fR(3X)
 483 wmove/\fBcurs_move\fR(3X)
 484 wnoutrefresh/\fBcurs_refresh\fR(3X)
 485 wprintw/\fBcurs_printw\fR(3X)
 486 wredrawln/\fBcurs_refresh\fR(3X)
 487 wrefresh/\fBcurs_refresh\fR(3X)
 488 wresize/\fBwresize\fR(3X)*
 489 wscanw/\fBcurs_scanw\fR(3X)
 490 wscrl/\fBcurs_scroll\fR(3X)
 491 wsetscrreg/\fBcurs_outopts\fR(3X)
 492 wstandend/\fBcurs_attr\fR(3X)
 493 wstandout/\fBcurs_attr\fR(3X)
 494 wsyncdown/\fBcurs_window\fR(3X)
 495 wsyncup/\fBcurs_window\fR(3X)
 496 wtimeout/\fBcurs_inopts\fR(3X)
 497 wtouchln/\fBcurs_touch\fR(3X)
 498 wvline/\fBcurs_border\fR(3X)
 499 .TE
 500 .SH RETURN VALUE
 501 Routines that return an integer return \fBERR\fR upon failure and an
 502 integer value other than \fBERR\fR upon successful completion, unless
 503 otherwise noted in the routine descriptions.
 504
 505 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
 506 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, \fBgetmaxyx\fR.  The return
 507 values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
 508 \fBgetmaxyx\fR are undefined (\fIi\fR.\fIe\fR., these should not be used as the
 509 right-hand side of assignment statements).
 510
 511 Routines that return pointers return \fBNULL\fR on error.
 512 .SH ENVIRONMENT
 513 The following environment symbols are useful for customizing the
 514 runtime behavior of the \fBncurses\fR library.  The most important
 515 ones have been already discussed in detail.
 516 .TP 5
 517 BAUDRATE
 518 The debugging library checks this environment symbol when the application
 519 has redirected output to a file.
 520 The symbol's numeric value is used for the baudrate.
 521 If no value is found \fBncurses\fR uses 9600.
 522 This allows testers to construct repeatable test-cases
 523 that take into account costs that depend on baudrate.
 524 .TP 5
 525 CC
 526 When set, change occurrences of the command_character
 527 (i.e., the \fBcmdch\fP capability)
 528 of the loaded terminfo entries to the value of this symbol.
 529 Very few terminfo entries provide this feature.
 530 .TP 5
 531 COLUMNS
 532 Specify the width of the screen in characters.
 533 Applications running in a windowing environment usually are able to
 534 obtain the width of the window in which they are executing.
 535 If neither the $COLUMNS value nor the terminal's screen size is available,
 536 \fBncurses\fR uses the size which may be specified in the terminfo database
 537 (i.e., the \fBcols\fR capability).
 538
 539 It is important that your application use a correct size for the screen.
 540 However, this is not always possible because your application may be
 541 running on a host which does not honor NAWS (Negotiations About Window
 542 Size), or because you are temporarily running as another user.
 543
 544 Either COLUMNS or LINES symbols may be specified independently.
 545 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
 546 e.g., xterm which commonly specifies a 65 line screen.
 547 For best results, \fBlines\fR and \fBcols\fR should not be specified in
 548 a terminal description for terminals which are run as emulations.
 549
 550 Use the \fBuse_env\fR function to disable this feature.
 551 .TP 5
 552 DISPLAY
 553 Provides a hint to ncurses that your terminal is an X terminal
 554 emulator such as \fBxterm\fP.
 555 If the \fBkmous\fP capability is set to the beginning of the xterm
 556 mouse response, e.g., "kmous=\E[M", then ncurses will send the terminal
 557 xterm's mouse initialization strings and allow appropriate replies.
 558 See the \fBcurs_mouse\fR(3X) manual page for programming information.
 559 .TP 5
 560 ESCDELAY
 561 Specifies the total time, in milliseconds, for which ncurses will
 562 await a character sequence, e.g., a function key.
 563 The default value, 1000 milliseconds, is enough for most uses.
 564 However, it is made a variable to accommodate unusual applications.
 565
 566 The most common instance where you may wish to change this value
 567 is to work with slow hosts, e.g., running on a network.
 568 If the host cannot read characters rapidly enough, it will have the same
 569 effect as if the terminal did not send characters rapidly enough.
 570 The library will still see a timeout.
 571
 572 Note that xterm mouse events are built up from character sequences
 573 received from the xterm.
 574 If your application makes heavy use of multiple-clicking, you may
 575 wish to lengthen this default value because the timeout applies
 576 to the composed multi-click event as well as the individual clicks.
 577 .TP 5
 578 HOME
 579 Tells \fBncurses\fR where your home directory is.
 580 That is where it may read and write auxiliary terminal descriptions:
 581
 582 $HOME/.termcap
 583 .br
 584 $HOME/.terminfo
 585 .TP 5
 586 LINES
 587 Like COLUMNS, specify the height of the screen in characters.
 588 See COLUMNS for a detailed description.
 589 .TP 5
 590 MOUSE_BUTTONS_123
 591 This applies only to the OS/2 EMX port.
 592 It specifies the order of buttons on the mouse.
 593 OS/2 numbers a 3-button mouse inconsistently from other
 594 platforms:
 595
 596 1 = left
 597 .br
 598 2 = right
 599 .br
 600 3 = middle.
 601
 602 This symbol lets you customize the mouse.
 603 The symbol must be three numeric digits 1-3 in any order, e.g., 123 or 321.
 604 If it is not specified, \fBncurses\fR uses 132.
 605 .TP 5
 606 NCURSES_NO_PADDING
 607 Most of the terminal descriptions in the terminfo database are written
 608 for real "hardware" terminals.
 609 Many people use terminal emulators
 610 which run in a windowing environment and use curses-based applications.
 611 Terminal emulators can duplicate
 612 all of the important aspects of a hardware terminal, but they do not
 613 have the same limitations.
 614 The chief limitation of a hardware terminal from the standpoint
 615 of your application is the management of dataflow, i.e., timing.
 616 Unless a hardware terminal is interfaced into a terminal concentrator
 617 (which does flow control),
 618 it (or your application) must manage dataflow, preventing overruns.
 619 The cheapest solution (no hardware cost)
 620 is for your program to do this by pausing after
 621 operations that the terminal does slowly, such as clearing the display.
 622
 623 As a result, many terminal descriptions (including the vt100)
 624 have delay times embedded.  You may wish to use these descriptions,
 625 but not want to pay the performance penalty.
 626
 627 Set the NCURSES_NO_PADDING symbol to disable all but mandatory
 628 padding.  Mandatory padding is used as a part of special control
 629 sequences such as \fIflash\fR.
 630 .TP 5
 631 NCURSES_NO_SETBUF
 632 Normally \fBncurses\fR enables buffered output during terminal initialization.
 633 This is done (as in SVr4 curses) for performance reasons.
 634 For testing purposes, both of \fBncurses\fR and certain applications,
 635 this feature is made optional.  Setting the NCURSES_NO_SETBUF variable
 636 disables output buffering, leaving the output in the original (usually
 637 line buffered) mode.
 638 .TP 5
 639 NCURSES_TRACE
 640 During initialization, the \fBncurses\fR debugging library
 641 checks the NCURSES_TRACE symbol.
 642 If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
 643 function, using that value as the argument.
 644
 645 The argument values, which are defined in \fBcurses.h\fR, provide several
 646 types of information.
 647 When running with traces enabled, your application will write the
 648 file \fBtrace\fR to the current directory.
 649 .TP 5
 650 TERM
 651 Denotes your terminal type.
 652 Each terminal type is distinct, though many are similar.
 653 .TP 5
 654 TERMCAP
 655 If the \fBncurses\fR library has been configured with \fItermcap\fR
 656 support, \fBncurses\fR will check for a terminal's description in
 657 termcap form if it is not available in the terminfo database.
 658
 659 The TERMCAP symbol contains either a terminal description (with
 660 newlines stripped out),
 661 or a file name telling where the information denoted by the TERM symbol exists.
 662 In either case, setting it directs \fBncurses\fR to ignore
 663 the usual place for this information, e.g., /etc/termcap.
 664 .TP 5
 665 TERMINFO
 666 Overrides the directory in which \fBncurses\fR searches for your terminal
 667 description.
 668 This is the simplest, but not the only way to change the list of directories.
 669 The complete list of directories in order follows:
 670 .RS
 671 .TP 3
 672 -
 673 the last directory to which \fBncurses\fR wrote, if any, is searched first.
 674 .TP 3
 675 -
 676 the directory specified by the TERMINFO symbol
 677 .TP 3
 678 -
 679 $HOME/.terminfo
 680 .TP 3
 681 -
 682 directories listed in the TERMINFO_DIRS symbol
 683 .TP 3
 684 -
 685 one or more directories whose names are configured and compiled into the
 686 ncurses library, e.g.,
 687 @DATADIR@/terminfo
 688 .RE
 689 .TP 5
 690 TERMINFO_DIRS
 691 Specifies a list of directories to search for terminal descriptions.
 692 The list is separated by colons (i.e., ":").
 693 All of the terminal descriptions are in terminfo form, which makes
 694 a subdirectory named for the first letter of the terminal names therein.
 695 .TP 5
 696 TERMPATH
 697 If TERMCAP does not hold a file name then \fBncurses\fR checks
 698 the TERMPATH symbol.
 699 This is a list of filenames separated by colons (i.e., ":").
 700 If the TERMPATH symbol is not set, \fBncurses\fR looks in the files
 701 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
 702 .SH FILES
 703 .TP 5
 704 @DATADIR@/tabset
 705 directory containing initialization files for the terminal capability database
 706 @DATADIR@/terminfo
 707 terminal capability database
 708 .SH SEE ALSO
 709 \fBterminfo\fR(\*n) and 3X pages whose names begin "curs_" for detailed routine
 710 descriptions.
 711 .SH EXTENSIONS
 712 The \fBncurses\fR library can be compiled with an option (\fB-DUSE_GETCAP\fR)
 713 that falls back to the old-style /etc/termcap file if the terminal setup code
 714 cannot find a terminfo entry corresponding to \fBTERM\fR.  Use of this feature
 715 is not recommended, as it essentially includes an entire termcap compiler in
 716 the \fBncurses\fR startup code, at significant cost in core and startup cycles.
 717
 718 The \fBncurses\fR library includes facilities for capturing mouse events on
 719 certain terminals (including xterm). See the \fBcurs_mouse\fR(3X)
 720 manual page for details.
 721
 722 The \fBncurses\fR library includes facilities for responding to window
 723 resizing events, e.g., when running in an xterm.
 724 See the \fBresizeterm\fR(3X)
 725 and \fBwresize\fR(3X) manual pages for details.
 726 In addition, the library may be configured with a SIGWINCH handler.
 727
 728 The \fBncurses\fR library extends the fixed set of function key capabilities
 729 of terminals by allowing the application designer to define additional
 730 key sequences at runtime.
 731 See the \fBdefine_key\fR(3X)
 732 and \fBkeyok\fR(3X) manual pages for details.
 733
 734 The \fBncurses\fR library can exploit the capabilities of terminals which
 735 implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an application
 736 to reset the terminal to its original foreground and background colors.
 737 From the users' perspective, the application is able to draw colored
 738 text on a background whose color is set independently, providing better
 739 control over color contrasts.
 740 See the \fBuse_default_colors\fR(3X) manual page for details.
 741
 742 The \fBncurses\fR library includes a function for directing application output
 743 to a printer attached to the terminal device.  See the \fBcurs_print\fR(3X)
 744 manual page for details.
 745 .SH PORTABILITY
 746 The \fBncurses\fR library is intended to be BASE-level conformant with the XSI
 747 Curses standard.  Certain portions of the EXTENDED XSI Curses functionality
 748 (including color support) are supported.  The following EXTENDED XSI Curses
 749 calls in support of wide (multibyte) characters are not yet implemented:
 750 \fBadd_wch\fP,
 751 \fBadd_wchnstr\fP,
 752 \fBadd_wchstr\fP,
 753 \fBaddnwstr\fP,
 754 \fBaddwstr\fP,
 755 \fBbkgrnd\fP,
 756 \fBbkgrndset\fP,
 757 \fBborder_set\fP,
 758 \fBbox_set\fP,
 759 \fBecho_wchar\fP,
 760 \fBerasewchar\fP,
 761 \fBget_wch\fP,
 762 \fBget_wstr\fP,
 763 \fBgetbkgrnd\fP,
 764 \fBgetcchar\fP,
 765 \fBgetn_wstr\fP,
 766 \fBgetwchtype\fP,
 767 \fBhline_set\fP,
 768 \fBin_wch\fP,
 769 \fBin_wchnstr\fP,
 770 \fBin_wchstr\fP,
 771 \fBinnwstr\fP,
 772 \fBins_nwstr\fP,
 773 \fBins_wch\fP,
 774 \fBins_wstr\fP,
 775 \fBinwchnstr\fP,
 776 \fBinwchstr\fP,
 777 \fBinwstr\fP,
 778 \fBkey_name\fP,
 779 \fBkillwchar\fP,
 780 \fBmvadd_wch\fP,
 781 \fBmvadd_wchnstr\fP,
 782 \fBmvadd_wchstr\fP,
 783 \fBmvaddnwstr\fP,
 784 \fBmvaddwstr\fP,
 785 \fBmvget_wch\fP,
 786 \fBmvget_wstr\fP,
 787 \fBmvgetn_wstr\fP,
 788 \fBmvhline_set\fP,
 789 \fBmvin_wch\fP,
 790 \fBmvinnwstr\fP,
 791 \fBmvins_nwstr\fP,
 792 \fBmvins_wch\fP,
 793 \fBmvins_wstr\fP,
 794 \fBmvinwchnstr\fP,
 795 \fBmvinwchstr\fP,
 796 \fBmvinwchstr\fP,
 797 \fBmvinwstr\fP,
 798 \fBmvvline_set\fP,
 799 \fBmvwadd_wch\fP,
 800 \fBmvwadd_wchnstr\fP,
 801 \fBmvwadd_wchstr\fP,
 802 \fBmvwaddnwstr\fP,
 803 \fBmvwaddwstr\fP,
 804 \fBmvwget_ch\fP,
 805 \fBmvwget_wch\fP,
 806 \fBmvwget_wstr\fP,
 807 \fBmvwgetn_wstr\fP,
 808 \fBmvwhline_set\fP,
 809 \fBmvwin_wch\fP,
 810 \fBmvwin_wchnstr\fP,
 811 \fBmvwin_wchstr\fP,
 812 \fBmvwinnwstr\fP,
 813 \fBmvwins_nwstr\fP,
 814 \fBmvwins_wch\fP,
 815 \fBmvwins_wstr\fP,
 816 \fBmvwinwchnstr\fP.
 817 \fBmvwinwstr\fP,
 818 \fBmvwvline_set\fP,
 819 \fBpecho_wchar\fP,
 820 \fBsetcchar\fP,
 821 \fBslk_wset\fP,
 822 \fBterm_attrs\fP,
 823 \fBunget_wch\fP,
 824 \fBvhline_set\fP,
 825 \fBvid_attr\fP,
 826 \fBvid_puts\fP,
 827 \fBvline_set\fP,
 828 \fBwadd_wch\fP,
 829 \fBwadd_wchnstr\fP,
 830 \fBwadd_wchstr\fP,
 831 \fBwaddnwstr\fP,
 832 \fBwaddwstr\fP,
 833 \fBwaddwstr\fP,
 834 \fBwbkgrnd\fP,
 835 \fBwbkgrndset\fP,
 836 \fBwbkgrndset\fP,
 837 \fBwborder_set\fP,
 838 \fBwecho_wchar\fP,
 839 \fBwecho_wchar\fP,
 840 \fBwget_wch\fP,
 841 \fBwget_wstr\fP,
 842 \fBwgetbkgrnd\fP,
 843 \fBwgetn_wstr\fP,
 844 \fBwhline_set\fP,
 845 \fBwin_wch\fP,
 846 \fBwin_wchnstr\fP,
 847 \fBwin_wchstr\fP,
 848 \fBwinnwstr\fP,
 849 \fBwins_nwstr\fP,
 850 \fBwins_wch\fP,
 851 \fBwins_wstr\fP,
 852 \fBwinwchnstr\fP,
 853 \fBwinwchstr\fP,
 854 \fBwinwstr\fP,
 855 \fBwunctrl\fP,
 856 \fBwvline_set\fP,
 857 .PP
 858 A small number of local differences (that is, individual differences between
 859 the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
 860 sections of the library man pages.
 861 .PP
 862 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.  See
 863 the \fBcurs_getch\fR(3X) manual page for details.
 864 .PP
 865 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.  See
 866 the \fBcurs_slk\fR(3X) manual page for details.
 867 .PP
 868 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
 869 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
 870 part of XPG4, nor are they present in SVr4.  See the \fBcurs_mouse\fR(3X)
 871 manual page for details.
 872 .PP
 873 The routine \fBmcprint\fR was not present in any previous curses
 874 implementation.  See the \fBcurs_print\fR(3X) manual page for details.
 875 .PP
 876 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.  See
 877 the \fBwresize\fR(3X) manual page for details.
 878 .PP
 879 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
 880 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
 881 bits in the UNIX tty driver.  In this implementation, all padding is done by
 882 NUL sends.  This method is slightly more expensive, but narrows the interface
 883 to the UNIX kernel significantly and increases the package's portability
 884 correspondingly.
 885 .PP
 886 In the XSI standard and SVr4 manual pages, many entry points have prototype
 887 arguments of the for \fBchar *const\fR (or \fBcchar_t *const\fR, or
 888 \fBwchar_t *const\fR, or \fBvoid *const\fR).  Depending on one's interpretation of the
 889 ANSI C standard (see section 3.5.4.1), these declarations are either (a)
 890 meaningless, or (b) meaningless and illegal.  The declaration
 891 \fBconst char *x\fR is a modifiable pointer to unmodifiable data, but
 892 \fBchar *const x\fR' is
 893 an unmodifiable pointer to modifiable data.  Given that C passes arguments by
 894 value, \fB<type> *const\fR as a formal type is at best dubious.  Some compilers
 895 choke on the prototypes.  Therefore, in this implementation, they have been
 896 changed to \fBconst <type> *\fR globally.
 897 .SH NOTES
 898 The header file \fB<curses.h>\fR automatically includes the header files
 899 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
 900
 901 If standard output from a \fBncurses\fR program is re-directed to something
 902 which is not a tty, screen updates will be directed to standard error.  This
 903 was an undocumented feature of AT&T System V Release 3 curses.
 904 .SH AUTHORS
 905 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
 906 Based on pcurses by Pavel Curtis.
 907 .\"#
 908 .\"# The following sets edit modes for GNU EMACS
 909 .\"# Local Variables:
 910 .\"# mode:nroff
 911 .\"# fill-column:79
 912 .\"# End: