man/ncurses.3x

   1 '\" t
   2 .\" $Id: ncurses.3x,v 1.23 1998/02/15 02:05:44 tom Exp $
   3 .TH ncurses 3X ""
   4 .ds n 5
   5 .ds d @DATADIR@/terminfo
   6 .SH NAME
   7 \fBncurses\fR - CRT screen handling and optimization package
   8 .SH SYNOPSIS
   9 \fB#include <curses.h>\fR
  10 .br
  11 .SH DESCRIPTION
  12 The \fBcurses\fR library routines give the user a terminal-independent method
  13 of updating character screens with reasonable optimization.  This
  14 implementation is ``new curses'' (ncurses) and is the approved replacement for
  15 4.4BSD classic curses, which has been discontinued.
  16
  17 The \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System V
  18 Release 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fR
  19 library is freely redistributable in source form.  Differences from the SVr4
  20 curses are summarized under the EXTENSIONS and BUGS sections below and
  21 described in detail in the EXTENSIONS and BUGS sections of individual man
  22 pages.
  23
  24 A program using these routines must be linked with the \fB-lncurses\fR option,
  25 or (if it has been generated) with the debugging library \fB-lncurses_g\fR.
  26 (Your system integrator may also have installed these libraries under
  27 the names \fB-lcurses\fR and \fB-lcurses_g\fR.)
  28 The ncurses_g library generates trace logs (in a file called 'trace' in the
  29 current directory) that describe curses actions.
  30
  31 The \fBncurses\fR package supports: overall screen, window and pad
  32 manipulation; output to windows and pads; reading terminal input; control over
  33 terminal and \fBcurses\fR input and output options; environment query
  34 routines; color manipulation; use of soft label keys; terminfo capabilities;
  35 and access to low-level terminal-manipulation routines.
  36
  37 To initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fR
  38 must be called before any of the other routines that deal with windows
  39 and screens are used.  The routine \fBendwin\fR must be called before
  40 exiting.  To get character-at-a-time input without echoing (most
  41 interactive, screen oriented programs want this), the following
  42 sequence should be used:
  43
  44       \fBinitscr(); cbreak(); noecho();\fR
  45
  46 Most programs would additionally use the sequence:
  47
  48       \fBnonl();\fR
  49       \fBintrflush(stdscr, FALSE);\fR
  50       \fBkeypad(stdscr, TRUE);\fR
  51
  52 Before a \fBcurses\fR program is run, the tab stops of the terminal
  53 should be set and its initialization strings, if defined, must be
  54 output.  This can be done by executing the \fBtput init\fR command
  55 after the shell environment variable \fBTERM\fR has been exported.
  56 \fBtset(1)\fR is usually responsible for doing this.
  57 [See \fBterminfo\fR(\*n) for further details.]
  58
  59 The \fBcurses\fR library permits manipulation of data structures,
  60 called \fIwindows\fR, which can be thought of as two-dimensional
  61 arrays of characters representing all or part of a CRT screen.  A
  62 default window called \fBstdscr\fR, which is the size of the terminal
  63 screen, is supplied.  Others may be created with \fBnewwin\fR.
  64
  65 Note that \fBcurses\fR does not handle overlapping windows, that's done by
  66 the \fBpanel\fR(3X) library. This means that you can either use
  67 \fBstdscr\fR or divide the screen into tiled windows and not using
  68 \fBstdscr\fR at all. Mixing the two will result in unpredictable, and
  69 undesired, effects.
  70
  71 Windows are referred to by variables declared as \fBWINDOW *\fR.
  72 These data structures are manipulated with routines described here and
  73 elsewhere in the \fBncurses\fR manual pages.  Among which the most basic
  74 routines are \fBmove\fR and \fBaddch\fR.  More general versions of
  75 these routines are included with names beginning with \fBw\fR,
  76 allowing the user to specify a window.  The routines not beginning
  77 with \fBw\fR affect \fBstdscr\fR.)
  78
  79 After using routines to manipulate a window, \fBrefresh\fR is called,
  80 telling \fBcurses\fR to make the user's CRT screen look like
  81 \fBstdscr\fR.  The characters in a window are actually of type
  82 \fBchtype\fR, (character and attribute data) so that other information
  83 about the character may also be stored with each character.
  84
  85 Special windows called \fIpads\fR may also be manipulated.  These are windows
  86 which are not constrained to the size of the screen and whose contents need not
  87 be completely displayed.  See \fBcurs_pad\fR(3X) for more information.
  88
  89 In addition to drawing characters on the screen, video attributes and colors
  90 may be supported, causing the characters to show up in such modes as
  91 underlined, in reverse video, or in color on terminals that support such
  92 display enhancements.  Line drawing characters may be specified to be output.
  93 On input, \fBcurses\fR is also able to translate arrow and function keys that
  94 transmit escape sequences into single values.  The video attributes, line
  95 drawing characters, and input values use names, defined in \fB<curses.h>\fR,
  96 such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
  97
  98 If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
  99 program is executing in a window environment, line and column information in
 100 the environment will override information read by \fIterminfo\fR.  This would
 101 effect a program running in an AT&T 630 layer, for example, where the size of a
 102 screen is changeable.
 103
 104 If the environment variable \fBTERMINFO\fR is defined, any program using
 105 \fBcurses\fR checks for a local terminal definition before checking in the
 106 standard place.  For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
 107 compiled terminal definition is found in
 108
 109       \fB\*d/a/att4424\fR.
 110
 111 (The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
 112 creation of huge directories.)  However, if \fBTERMINFO\fR is set to
 113 \fB$HOME/myterms\fR, \fBcurses\fR first checks
 114
 115       \fB$HOME/myterms/a/att4424\fR,
 116
 117 and if that fails, it then checks
 118
 119       \fB\*d/a/att4424\fR.
 120
 121 This is useful for developing experimental definitions or when write
 122 permission in \fB\*d\fR is not available.
 123
 124 The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
 125 \fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
 126 screen.  The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
 127 \fB0\fR, respectively.
 128
 129 The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
 130 which is used for certain low-level operations like clearing and redrawing a
 131 screen containing garbage.  The \fBcurscr\fR can be used in only a few
 132 routines.
 133
 134 .SS Routine and Argument Names
 135 Many \fBcurses\fR routines have two or more versions.  The routines prefixed
 136 with \fBw\fR require a window argument.  The routines prefixed with \fBp\fR
 137 require a pad argument.  Those without a prefix generally use \fBstdscr\fR.
 138
 139 The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
 140 coordinate to move to before performing the appropriate action.  The
 141 \fBmv\fR routines imply a call to \fBmove\fR before the call to the
 142 other routine.  The coordinate \fIy\fR always refers to the row (of
 143 the window), and \fIx\fR always refers to the column.  The upper
 144 left-hand corner is always (0,0), not (1,1).
 145
 146 The routines prefixed with \fBmvw\fR take both a window argument and
 147 \fIx\fR and \fIy\fR coordinates.  The window argument is always
 148 specified before the coordinates.
 149
 150 In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
 151 pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
 152 \fBWINDOW\fR.
 153
 154 Option setting routines require a Boolean flag \fIbf\fR with the value
 155 \fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.  The
 156 variables \fIch\fR and \fIattrs\fR below are always of type
 157 \fBchtype\fR.  The types \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and
 158 \fBchtype\fR are defined in \fB<curses.h>\fR.  The type \fBTERMINAL\fR
 159 is defined in \fB<term.h>\fR.  All other arguments are integers.
 160
 161 .SS Routine Name Index
 162 The following table lists each \fBcurses\fR routine and the name of
 163 the manual page on which it is described.  Routines flagged with `*'
 164 are ncurses-specific, not described by XPG4 or present in SVr4.
 165
 166 .TS
 167 center tab(/);
 168 l l
 169 l l .
 170 \fBcurses\fR Routine Name/Manual Page Name
 171 =
 172 addch/\fBcurs_addch\fR(3X)
 173 addchnstr/\fBcurs_addchstr\fR(3X)
 174 addchstr/\fBcurs_addchstr\fR(3X)
 175 addnstr/\fBcurs_addstr\fR(3X)
 176 addstr/\fBcurs_addstr\fR(3X)
 177 attroff/\fBcurs_attr\fR(3X)
 178 attron/\fBcurs_attr\fR(3X)
 179 attrset/\fBcurs_attr\fR(3X)
 180 baudrate/\fBcurs_termattrs\fR(3X)
 181 beep/\fBcurs_beep\fR(3X)
 182 bkgd/\fBcurs_bkgd\fR(3X)
 183 bkgdset/\fBcurs_bkgd\fR(3X)
 184 border/\fBcurs_border\fR(3X)
 185 box/\fBcurs_border\fR(3X)
 186 can_change_color/\fBcurs_color\fR(3X)
 187 cbreak/\fBcurs_inopts\fR(3X)
 188 clear/\fBcurs_clear\fR(3X)
 189 clearok/\fBcurs_outopts\fR(3X)
 190 clrtobot/\fBcurs_clear\fR(3X)
 191 clrtoeol/\fBcurs_clear\fR(3X)
 192 color_content/\fBcurs_color\fR(3X)
 193 copywin/\fBcurs_overlay\fR(3X)
 194 curs_set/\fBcurs_kernel\fR(3X)
 195 def_prog_mode/\fBcurs_kernel\fR(3X)
 196 def_shell_mode/\fBcurs_kernel\fR(3X)
 197 define_key/\fBdefine_key\fR(3X)*
 198 del_curterm/\fBcurs_terminfo\fR(3X)
 199 delay_output/\fBcurs_util\fR(3X)
 200 delch/\fBcurs_delch\fR(3X)
 201 deleteln/\fBcurs_deleteln\fR(3X)
 202 delscreen/\fBcurs_initscr\fR(3X)
 203 delwin/\fBcurs_window\fR(3X)
 204 derwin/\fBcurs_window\fR(3X)
 205 doupdate/\fBcurs_refresh\fR(3X)
 206 dupwin/\fBcurs_window\fR(3X)
 207 echo/\fBcurs_inopts\fR(3X)
 208 echochar/\fBcurs_addch\fR(3X)
 209 endwin/\fBcurs_initscr\fR(3X)
 210 erase/\fBcurs_clear\fR(3X)
 211 erasechar/\fBcurs_termattrs\fR(3X)
 212 filter/\fBcurs_util\fR(3X)
 213 flash/\fBcurs_beep\fR(3X)
 214 flushinp/\fBcurs_util\fR(3X)
 215 getbegyx/\fBcurs_getyx\fR(3X)
 216 getch/\fBcurs_getch\fR(3X)
 217 getmaxyx/\fBcurs_getyx\fR(3X)
 218 getmouse/\fBcurs_mouse\fR(3X)*
 219 getparyx/\fBcurs_getyx\fR(3X)
 220 getstr/\fBcurs_getstr\fR(3X)
 221 getsyx/\fBcurs_kernel\fR(3X)
 222 getwin/\fBcurs_util\fR(3X)
 223 getyx/\fBcurs_getyx\fR(3X)
 224 halfdelay/\fBcurs_inopts\fR(3X)
 225 has_colors/\fBcurs_color\fR(3X)
 226 has_ic/\fBcurs_termattrs\fR(3X)
 227 has_il/\fBcurs_termattrs\fR(3X)
 228 has_key/\fBcurs_getch\fR(3X)*
 229 hline/\fBcurs_border\fR(3X)
 230 idcok/\fBcurs_outopts\fR(3X)
 231 idlok/\fBcurs_outopts\fR(3X)
 232 immedok/\fBcurs_outopts\fR(3X)
 233 inch/\fBcurs_inch\fR(3X)
 234 inchnstr/\fBcurs_inchstr\fR(3X)
 235 inchstr/\fBcurs_inchstr\fR(3X)
 236 init_color/\fBcurs_color\fR(3X)
 237 init_pair/\fBcurs_color\fR(3X)
 238 initscr/\fBcurs_initscr\fR(3X)
 239 innstr/\fBcurs_instr\fR(3X)
 240 insch/\fBcurs_insch\fR(3X)
 241 insdelln/\fBcurs_deleteln\fR(3X)
 242 insertln/\fBcurs_deleteln\fR(3X)
 243 insnstr/\fBcurs_insstr\fR(3X)
 244 insstr/\fBcurs_insstr\fR(3X)
 245 instr/\fBcurs_instr\fR(3X)
 246 intrflush/\fBcurs_inopts\fR(3X)
 247 is_linetouched/\fBcurs_touch\fR(3X)
 248 is_wintouched/\fBcurs_touch\fR(3X)
 249 isendwin/\fBcurs_initscr\fR(3X)
 250 keyname/\fBcurs_util\fR(3X)
 251 keyok/\fBkeyok\fR(3X)*
 252 keypad/\fBcurs_inopts\fR(3X)
 253 killchar/\fBcurs_termattrs\fR(3X)
 254 leaveok/\fBcurs_outopts\fR(3X)
 255 longname/\fBcurs_termattrs\fR(3X)
 256 mcprint/\fBcurs_print\fR(3X)*
 257 meta/\fBcurs_inopts\fR(3X)
 258 mouseinterval/\fBcurs_mouse\fR(3X)*
 259 mousemask/\fBcurs_mouse\fR(3X)*
 260 move/\fBcurs_move\fR(3X)
 261 mvaddch/\fBcurs_addch\fR(3X)
 262 mvaddchnstr/\fBcurs_addchstr\fR(3X)
 263 mvaddchstr/\fBcurs_addchstr\fR(3X)
 264 mvaddnstr/\fBcurs_addstr\fR(3X)
 265 mvaddstr/\fBcurs_addstr\fR(3X)
 266 mvcur/\fBcurs_terminfo\fR(3X)
 267 mvdelch/\fBcurs_delch\fR(3X)
 268 mvderwin/\fBcurs_window\fR(3X)
 269 mvgetch/\fBcurs_getch\fR(3X)
 270 mvgetstr/\fBcurs_getstr\fR(3X)
 271 mvinch/\fBcurs_inch\fR(3X)
 272 mvinchnstr/\fBcurs_inchstr\fR(3X)
 273 mvinchstr/\fBcurs_inchstr\fR(3X)
 274 mvinnstr/\fBcurs_instr\fR(3X)
 275 mvinsch/\fBcurs_insch\fR(3X)
 276 mvinsnstr/\fBcurs_insstr\fR(3X)
 277 mvinsstr/\fBcurs_insstr\fR(3X)
 278 mvinstr/\fBcurs_instr\fR(3X)
 279 mvprintw/\fBcurs_printw\fR(3X)
 280 mvscanw/\fBcurs_scanw\fR(3X)
 281 mvwaddch/\fBcurs_addch\fR(3X)
 282 mvwaddchnstr/\fBcurs_addchstr\fR(3X)
 283 mvwaddchstr/\fBcurs_addchstr\fR(3X)
 284 mvwaddnstr/\fBcurs_addstr\fR(3X)
 285 mvwaddstr/\fBcurs_addstr\fR(3X)
 286 mvwdelch/\fBcurs_delch\fR(3X)
 287 mvwgetch/\fBcurs_getch\fR(3X)
 288 mvwgetstr/\fBcurs_getstr\fR(3X)
 289 mvwin/\fBcurs_window\fR(3X)
 290 mvwinch/\fBcurs_inch\fR(3X)
 291 mvwinchnstr/\fBcurs_inchstr\fR(3X)
 292 mvwinchstr/\fBcurs_inchstr\fR(3X)
 293 mvwinnstr/\fBcurs_instr\fR(3X)
 294 mvwinsch/\fBcurs_insch\fR(3X)
 295 mvwinsnstr/\fBcurs_insstr\fR(3X)
 296 mvwinsstr/\fBcurs_insstr\fR(3X)
 297 mvwinstr/\fBcurs_instr\fR(3X)
 298 mvwprintw/\fBcurs_printw\fR(3X)
 299 mvwscanw/\fBcurs_scanw\fR(3X)
 300 napms/\fBcurs_kernel\fR(3X)
 301 newpad/\fBcurs_pad\fR(3X)
 302 newterm/\fBcurs_initscr\fR(3X)
 303 newwin/\fBcurs_window\fR(3X)
 304 nl/\fBcurs_outopts\fR(3X)
 305 nocbreak/\fBcurs_inopts\fR(3X)
 306 nodelay/\fBcurs_inopts\fR(3X)
 307 noecho/\fBcurs_inopts\fR(3X)
 308 nonl/\fBcurs_outopts\fR(3X)
 309 noqiflush/\fBcurs_inopts\fR(3X)
 310 noraw/\fBcurs_inopts\fR(3X)
 311 notimeout/\fBcurs_inopts\fR(3X)
 312 overlay/\fBcurs_overlay\fR(3X)
 313 overwrite/\fBcurs_overlay\fR(3X)
 314 pair_content/\fBcurs_color\fR(3X)
 315 pechochar/\fBcurs_pad\fR(3X)
 316 pnoutrefresh/\fBcurs_pad\fR(3X)
 317 prefresh/\fBcurs_pad\fR(3X)
 318 printw/\fBcurs_printw\fR(3X)
 319 putp/\fBcurs_terminfo\fR(3X)
 320 putwin/\fBcurs_util\fR(3X)
 321 qiflush/\fBcurs_inopts\fR(3X)
 322 raw/\fBcurs_inopts\fR(3X)
 323 redrawwin/\fBcurs_refresh\fR(3X)
 324 refresh/\fBcurs_refresh\fR(3X)
 325 reset_prog_mode/\fBcurs_kernel\fR(3X)
 326 reset_shell_mode/\fBcurs_kernel\fR(3X)
 327 resetty/\fBcurs_kernel\fR(3X)
 328 resizeterm/\fBresizeterm\fR(3X)*
 329 restartterm/\fBcurs_terminfo\fR(3X)
 330 ripoffline/\fBcurs_kernel\fR(3X)
 331 savetty/\fBcurs_kernel\fR(3X)
 332 scanw/\fBcurs_scanw\fR(3X)
 333 scr_dump/\fBcurs_scr_dump\fR(3X)
 334 scr_init/\fBcurs_scr_dump\fR(3X)
 335 scr_restore/\fBcurs_scr_dump\fR(3X)
 336 scr_set/\fBcurs_scr_dump\fR(3X)
 337 scrl/\fBcurs_scroll\fR(3X)
 338 scroll/\fBcurs_scroll\fR(3X)
 339 scrollok/\fBcurs_outopts\fR(3X)
 340 set_curterm/\fBcurs_terminfo\fR(3X)
 341 set_term/\fBcurs_initscr\fR(3X)
 342 setscrreg/\fBcurs_outopts\fR(3X)
 343 setsyx/\fBcurs_kernel\fR(3X)
 344 setterm/\fBcurs_terminfo\fR(3X)
 345 setupterm/\fBcurs_terminfo\fR(3X)
 346 slk_attr/\fBcurs_slk\fR(3X)*
 347 slk_attroff/\fBcurs_slk\fR(3X)
 348 slk_attron/\fBcurs_slk\fR(3X)
 349 slk_attrset/\fBcurs_slk\fR(3X)
 350 slk_clear/\fBcurs_slk\fR(3X)
 351 slk_init/\fBcurs_slk\fR(3X)
 352 slk_label/\fBcurs_slk\fR(3X)
 353 slk_noutrefresh/\fBcurs_slk\fR(3X)
 354 slk_refresh/\fBcurs_slk\fR(3X)
 355 slk_restore/\fBcurs_slk\fR(3X)
 356 slk_set/\fBcurs_slk\fR(3X)
 357 slk_touch/\fBcurs_slk\fR(3X)
 358 standend/\fBcurs_attr\fR(3X)
 359 standout/\fBcurs_attr\fR(3X)
 360 start_color/\fBcurs_color\fR(3X)
 361 subpad/\fBcurs_pad\fR(3X)
 362 subwin/\fBcurs_window\fR(3X)
 363 syncok/\fBcurs_window\fR(3X)
 364 termattrs/\fBcurs_termattrs\fR(3X)
 365 termname/\fBcurs_termattrs\fR(3X)
 366 tgetent/\fBcurs_termcap\fR(3X)
 367 tgetflag/\fBcurs_termcap\fR(3X)
 368 tgetnum/\fBcurs_termcap\fR(3X)
 369 tgetstr/\fBcurs_termcap\fR(3X)
 370 tgoto/\fBcurs_termcap\fR(3X)
 371 tigetflag/\fBcurs_terminfo\fR(3X)
 372 tigetnum/\fBcurs_terminfo\fR(3X)
 373 tigetstr/\fBcurs_terminfo\fR(3X)
 374 timeout/\fBcurs_inopts\fR(3X)
 375 touchline/\fBcurs_touch\fR(3X)
 376 touchwin/\fBcurs_touch\fR(3X)
 377 tparm/\fBcurs_terminfo\fR(3X)
 378 tputs/\fBcurs_termcap\fR(3X)
 379 tputs/\fBcurs_terminfo\fR(3X)
 380 typeahead/\fBcurs_inopts\fR(3X)
 381 unctrl/\fBcurs_util\fR(3X)
 382 ungetch/\fBcurs_getch\fR(3X)
 383 ungetmouse/\fBcurs_mouse\fR(3X)*
 384 untouchwin/\fBcurs_touch\fR(3X)
 385 use_default_colors/\fBdft_fgbg\fR(3X)*
 386 use_env/\fBcurs_util\fR(3X)
 387 vidattr/\fBcurs_terminfo\fR(3X)
 388 vidputs/\fBcurs_terminfo\fR(3X)
 389 vline/\fBcurs_border\fR(3X)
 390 vwprintw/\fBcurs_printw\fR(3X)
 391 vwscanw/\fBcurs_scanw\fR(3X)
 392 waddch/\fBcurs_addch\fR(3X)
 393 waddchnstr/\fBcurs_addchstr\fR(3X)
 394 waddchstr/\fBcurs_addchstr\fR(3X)
 395 waddnstr/\fBcurs_addstr\fR(3X)
 396 waddstr/\fBcurs_addstr\fR(3X)
 397 wattroff/\fBcurs_attr\fR(3X)
 398 wattron/\fBcurs_attr\fR(3X)
 399 wattrset/\fBcurs_attr\fR(3X)
 400 wbkgd/\fBcurs_bkgd\fR(3X)
 401 wbkgdset/\fBcurs_bkgd\fR(3X)
 402 wborder/\fBcurs_border\fR(3X)
 403 wclear/\fBcurs_clear\fR(3X)
 404 wclrtobot/\fBcurs_clear\fR(3X)
 405 wclrtoeol/\fBcurs_clear\fR(3X)
 406 wcursyncup/\fBcurs_window\fR(3X)
 407 wdelch/\fBcurs_delch\fR(3X)
 408 wdeleteln/\fBcurs_deleteln\fR(3X)
 409 wechochar/\fBcurs_addch\fR(3X)
 410 wenclose/\fBcurs_mouse\fR(3X)*
 411 werase/\fBcurs_clear\fR(3X)
 412 wgetch/\fBcurs_getch\fR(3X)
 413 wgetnstr/\fBcurs_getstr\fR(3X)
 414 wgetstr/\fBcurs_getstr\fR(3X)
 415 whline/\fBcurs_border\fR(3X)
 416 winch/\fBcurs_inch\fR(3X)
 417 winchnstr/\fBcurs_inchstr\fR(3X)
 418 winchstr/\fBcurs_inchstr\fR(3X)
 419 winnstr/\fBcurs_instr\fR(3X)
 420 winsch/\fBcurs_insch\fR(3X)
 421 winsdelln/\fBcurs_deleteln\fR(3X)
 422 winsertln/\fBcurs_deleteln\fR(3X)
 423 winsnstr/\fBcurs_insstr\fR(3X)
 424 winsstr/\fBcurs_insstr\fR(3X)
 425 winstr/\fBcurs_instr\fR(3X)
 426 wmove/\fBcurs_move\fR(3X)
 427 wnoutrefresh/\fBcurs_refresh\fR(3X)
 428 wprintw/\fBcurs_printw\fR(3X)
 429 wredrawln/\fBcurs_refresh\fR(3X)
 430 wrefresh/\fBcurs_refresh\fR(3X)
 431 wresize/\fBwresize\fR(3X)*
 432 wscanw/\fBcurs_scanw\fR(3X)
 433 wscrl/\fBcurs_scroll\fR(3X)
 434 wsetscrreg/\fBcurs_outopts\fR(3X)
 435 wstandend/\fBcurs_attr\fR(3X)
 436 wstandout/\fBcurs_attr\fR(3X)
 437 wsyncdown/\fBcurs_window\fR(3X)
 438 wsyncup/\fBcurs_window\fR(3X)
 439 wtimeout/\fBcurs_inopts\fR(3X)
 440 wtouchln/\fBcurs_touch\fR(3X)
 441 wvline/\fBcurs_border\fR(3X)
 442 .TE
 443 .SH RETURN VALUE
 444 Routines that return an integer return \fBERR\fR upon failure and an
 445 integer value other than \fBERR\fR upon successful completion, unless
 446 otherwise noted in the routine descriptions.
 447
 448 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
 449 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, \fBgetmaxyx\fR.  The return
 450 values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
 451 \fBgetmaxyx\fR are undefined (\fIi\fR.\fIe\fR., these should not be used as the
 452 right-hand side of assignment statements).
 453
 454 Routines that return pointers return \fBNULL\fR on error.
 455 .SH SEE ALSO
 456 \fBterminfo\fR(\*n) and 3X pages whose names begin "curs_" for detailed routine
 457 descriptions.
 458 .SH EXTENSIONS
 459 The \fBcurses\fR library can be compiled with an option (\fB-DTERMCAP_FILE\fR)
 460 that falls back to the old-style /etc/termcap file if the terminal setup code
 461 cannot find a terminfo entry corresponding to \fBTERM\fR.  Use of this feature
 462 is not recommended, as it essentially includes an entire termcap compiler in
 463 the \fBcurses\fR startup code, at significant cost in core and startup cycles.
 464
 465 Compiling with \fB-DTERMCAP_FILE\fR changes the library's initialization
 466 sequence in a way intended to mimic the behavior of 4.4BSD curses.  If there is
 467 no local or system terminfo entry matching \fBTERM\fR, then the library looks
 468 for termcap entries in the following places: (1) if \fBTERMINFO\fR is
 469 undefined, in the file named by \fBTERMCAP_FILE\fR; (2) if \fBTERMINFO\fR is
 470 defined and begins with a slash, it is interpreted as the name of a termcap
 471 file to search for \fBTERM\fR; (3) otherwise, if \fBTERMINFO\fR has a leading
 472 string that looks like a terminal entry name list, and it matches \fBTERM\fR,
 473 the contents of \fBTERMINFO\fR is interpreted as a termcap; (4) if
 474 \fBTERMINFO\fR looks like a termcap but doesn't match \fBTERM\fR, the termcap
 475 file is searched for among the colon-separated paths in the environment
 476 variable \fBTERMPATHS\fR if that is defined, and in ~/.termcap and the file
 477 value of \fBTERMCAP_FILE\fR otherwise.
 478
 479 Versions of \fBcurses\fR compiled on PC clones support display of the PC ROM
 480 characters (including ROM characters 0-31, which stock SVr4 curses cannot
 481 display). See the EXTENSIONS sections of \fBcurs_addch\fR(3X) and
 482 \fBcurs_attr\fR(3X).
 483
 484 The \fBcurses\fR library includes facilities for capturing mouse events on
 485 certain terminals (including xterm). See the \fBcurs_mouse\fR(3X)
 486 manual page for details.
 487
 488 The \fBcurses\fR library includes a function for directing application output
 489 to a printer attached to the terminal device.  See the \fBcurs_print\fR(3X)
 490 manual page for details.
 491 .SH PORTABILITY
 492 The \fBcurses\fR library is intended to be BASE-level conformant with the XSI
 493 Curses standard.  Certain portions of the EXTENDED XSI Curses functionality
 494 (including color support) are supported.  The following EXTENDED XSI Curses
 495 calls in support of wide (multibyte) characters are not yet implemented:
 496 \fBaddnwstr\fB,
 497 \fBaddwstr\fB,
 498 \fBmvaddnwstr\fB,
 499 \fBmvwaddnwstr\fB,
 500 \fBmvaddwstr\fB,
 501 \fBwaddnwstr\fB,
 502 \fBwaddwstr\fB,
 503 \fBadd_wch\fB,
 504 \fBwadd_wch\fB,
 505 \fBmvadd_wch\fB,
 506 \fBmvwadd_wch\fB,
 507 \fBadd_wchnstr\fB,
 508 \fBadd_wchstr\fB,
 509 \fBwadd_wchnstr\fB,
 510 \fBwadd_wchstr\fB,
 511 \fBmvadd_wchnstr\fB,
 512 \fBmvadd_wchstr\fB,
 513 \fBmvwadd_wchnstr\fB,
 514 \fBmvwadd_wchstr\fB,
 515 \fBbkgrndset\fB,
 516 \fBbkgrnd\fB,
 517 \fBgetbkgrnd\fB,
 518 \fBwbkgrnd\fB,
 519 \fBwbkgrndset\fB,
 520 \fBwgetbkgrnd\fB,
 521 \fBborder_set\fB,
 522 \fBwborder_set\fB,
 523 \fBbox_set\fB,
 524 \fBhline_set\fB,
 525 \fBmvhline_set\fB,
 526 \fBmvvline_set\fB,
 527 \fBmvwhline_set\fB,
 528 \fBmvwvline_set\fB,
 529 \fBwhline_set\fB,
 530 \fBvhline_set\fB,
 531 \fBwvline_set\fB,
 532 \fBecho_wchar\fB,
 533 \fBwecho_wchar\fB,
 534 \fBerasewchar\fB,
 535 \fBkillwchar\fB,
 536 \fBget_wch\fB,
 537 \fBmvget_wch\fB,
 538 \fBmvwget_ch\fB,
 539 \fBwget_wch\fB,
 540 \fBgetwchtype\fB,
 541 \fBget_wstr\fB,
 542 \fBgetn_wstr\fB,
 543 \fBwget_wstr\fB,
 544 \fBwgetn_wstr\fB,
 545 \fBmvget_wstr\fB,
 546 \fBmvgetn_wstr\fB,
 547 \fBmvwget_wstr\fB,
 548 \fBmvwgetn_wstr\fB,
 549 \fBinnwstr\fB,
 550 \fBinwstr\fB,
 551 \fBwinnwstr\fB,
 552 \fBwinwstr\fB,
 553 \fBmvinnwstr\fB,
 554 \fBmvinwstr\fB,
 555 \fBmvwinnwstr\fB,
 556 \fBmvwinwstr\fB,
 557 \fBins_nwstr\fB,
 558 \fBins_wstr\fB,
 559 \fBmvins_nwstr\fB,
 560 \fBmvins_wstr\fB,
 561 \fBmvwins_nwstr\fB,
 562 \fBmvwins_wstr\fB,
 563 \fBwins_nwstr\fB,
 564 \fBwins_wstr\fB,
 565 \fBins_wch\fB,
 566 \fBwins_wch\fB,
 567 \fBmvins_wch\fB,
 568 \fBmvwins_wch\fB,
 569 \fBin_wch\fB,
 570 \fBwin_wch\fB,
 571 \fBmvin_wch\fB,
 572 \fBmvwin_wch\fB,
 573 \fBinwchstr\fB,
 574 \fBinwchnstr\fB,
 575 \fBwinwchstr\fB,
 576 \fBwinwchnstr\fB,
 577 \fBmvinwchstr\fB,
 578 \fBmvinwchnstr\fB,
 579 \fBmvinwchstr\fB,
 580 \fBmvwinwchnstr\fB.
 581 .PP
 582 A small number of local differences (that is, individual differences between
 583 the XSI Curses and \fBcurses\fR calls) are described in \fBPORTABILITY\fR
 584 sections of the library man pages.
 585 .PP
 586 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.  See
 587 the \fBcurs_getch\fR(3X) manual page for details.
 588 .PP
 589 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.  See
 590 the \fBcurs_slk\fR(3X) manual page for details.
 591 .PP
 592 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
 593 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
 594 part of XPG4, nor are they present in SVr4.  See the \fBcurs_mouse\fR(3X)
 595 manual page for details.
 596 .PP
 597 The routine \fBmcprint\fR was not present in any previous curses
 598 implementation.  See the \fBcurs_print\fR(3X) manual page for details.
 599 .PP
 600 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.  See
 601 the \fBwresize\fR(3X) manual page for details.
 602 .PP
 603 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
 604 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
 605 bits in the UNIX tty driver.  In this implementation, all padding is done by
 606 NUL sends.  This method is slightly more expensive, but narrows the interface
 607 to the UNIX kernel significantly and increases the package's portability
 608 correspondingly.
 609 .PP
 610 In the XSI standard and SVr4 manual pages, many entry points have prototype
 611 arguments of the for \fBchar *const\fR (or \fBcchar_t *const\fR, or \fBwchar_t
 612 *const\fR, or \fBvoid *const\fR).  Depending on one's interpretation of the
 613 ANSI C standard (see section 3.5.4.1), these declarations are either (a)
 614 meaningless, or (b) meaningless and illegal.  The declaration \fBconst char
 615 *x\fR is a modifiable pointer to unmodifiable data, but \fBchar *const x\fR' is
 616 an unmodifiable pointer to modifiable data.  Given that C passes arguments by
 617 value, \fB<type> *const\fR as a formal type is at best dubious.  Some compilers
 618 choke on the prototypes.  Therefore, in this implementation, they have been
 619 changed to \fBconst <type> *\fR globally.
 620 .SH NOTES
 621 The header file \fB<curses.h>\fR automatically includes the header files
 622 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
 623
 624 If standard output from a \fBcurses\fR program is re-directed to something
 625 which is not a tty, screen updates will be directed to standard error.  This
 626 was an undocumented feature of AT&T System V Release 3 curses.
 627 .SH AUTHORS
 628 Zeyd M. Ben-Halim, Eric S. Raymond.  Descends from the original pcurses
 629 by Pavel Curtis.
 630 .\"#
 631 .\"# The following sets edit modes for GNU EMACS
 632 .\"# Local Variables:
 633 .\"# mode:nroff
 634 .\"# fill-column:79
 635 .\"# End: