'\" t.\"***************************************************************************.\" Copyright (c) 1998-2003,2004 Free Software Foundation, Inc.              *.\"                                                                          *.\" Permission is hereby granted, free of charge, to any person obtaining a  *.\" copy of this software and associated documentation files (the            *.\" "Software"), to deal in the Software without restriction, including      *.\" without limitation the rights to use, copy, modify, merge, publish,      *.\" distribute, distribute with modifications, sublicense, and/or sell       *.\" copies of the Software, and to permit persons to whom the Software is    *.\" furnished to do so, subject to the following conditions:                 *.\"                                                                          *.\" The above copyright notice and this permission notice shall be included  *.\" in all copies or substantial portions of the Software.                   *.\"                                                                          *.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *.\"                                                                          *.\" Except as contained in this notice, the name(s) of the above copyright   *.\" holders shall not be used in advertising or otherwise to promote the     *.\" sale, use or other dealings in this Software without prior written       *.\" authorization.                                                           *.\"***************************************************************************.\".\" $Id: ncurses.3x,v 1.70 2004/01/11 01:45:54 tom Exp $.hy 0.TH ncurses 3X "".ds n 5.ds d @TERMINFO@.SH NAME\fBncurses\fR - CRT screen handling and optimization package.SH SYNOPSIS\fB#include <curses.h>\fR.br.SH DESCRIPTIONThe \fBncurses\fR library routines give the user a terminal-independent methodof updating character screens with reasonable optimization.  Thisimplementation is ``new curses'' (ncurses) and is the approved replacement for4.4BSD classic curses, which has been discontinued..PPThe \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System VRelease 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fRlibrary is freely redistributable in source form.  Differences from the SVr4curses are summarized under the EXTENSIONS and BUGS sections below anddescribed in detail in the EXTENSIONS and BUGS sections of individual manpages..PPA program using these routines must be linked with the \fB-lncurses\fR option,or (if it has been generated) with the debugging library \fB-lncurses_g\fR.(Your system integrator may also have installed these libraries underthe names \fB-lcurses\fR and \fB-lcurses_g\fR.)The ncurses_g library generates trace logs (in a file called 'trace' in thecurrent directory) that describe curses actions..PPThe \fBncurses\fR package supports: overall screen, window and padmanipulation; output to windows and pads; reading terminal input; control overterminal and \fBcurses\fR input and output options; environment queryroutines; color manipulation; use of soft label keys; terminfo capabilities;and access to low-level terminal-manipulation routines..PPTo initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fRmust be called before any of the other routines that deal with windowsand screens are used.  The routine \fBendwin\fR must be called beforeexiting.  To get character-at-a-time input without echoing (mostinteractive, screen oriented programs want this), the followingsequence should be used:.sp      \fBinitscr(); cbreak(); noecho();\fR.spMost programs would additionally use the sequence:.sp      \fBnonl();\fR      \fBintrflush(stdscr, FALSE);\fR      \fBkeypad(stdscr, TRUE);\fR.spBefore a \fBcurses\fR program is run, the tab stops of the terminalshould be set and its initialization strings, if defined, must beoutput.  This can be done by executing the \fBtput init\fR commandafter the shell environment variable \fBTERM\fR has been exported.\fBtset(1)\fR is usually responsible for doing this.[See \fBterminfo\fR(\*n) for further details.].PPThe \fBncurses\fR library permits manipulation of data structures,called \fIwindows\fR, which can be thought of as two-dimensionalarrays of characters representing all or part of a CRT screen.  Adefault window called \fBstdscr\fR, which is the size of the terminalscreen, is supplied.  Others may be created with \fBnewwin\fR..PPNote that \fBcurses\fR does not handle overlapping windows, that's done bythe \fBpanel\fR(3X) library. This means that you can either use\fBstdscr\fR or divide the screen into tiled windows and not using\fBstdscr\fR at all. Mixing the two will result in unpredictable, andundesired, effects..PPWindows are referred to by variables declared as \fBWINDOW *\fR.These data structures are manipulated with routines described here andelsewhere in the \fBncurses\fR manual pages.  Among which the most basicroutines are \fBmove\fR and \fBaddch\fR.  More general versions ofthese routines are included with names beginning with \fBw\fR,allowing the user to specify a window.  The routines not beginningwith \fBw\fR affect \fBstdscr\fR.).PPAfter using routines to manipulate a window, \fBrefresh\fR is called,telling \fBcurses\fR to make the user's CRT screen look like\fBstdscr\fR.  The characters in a window are actually of type\fBchtype\fR, (character and attribute data) so that other informationabout the character may also be stored with each character..PPSpecial windows called \fIpads\fR may also be manipulated.  These are windowswhich are not constrained to the size of the screen and whose contents need notbe completely displayed.  See \fBcurs_pad\fR(3X) for more information..PPIn addition to drawing characters on the screen, video attributes and colorsmay be supported, causing the characters to show up in such modes asunderlined, in reverse video, or in color on terminals that support suchdisplay enhancements.  Line drawing characters may be specified to be output.On input, \fBcurses\fR is also able to translate arrow and function keys thattransmit escape sequences into single values.  The video attributes, linedrawing characters, and input values use names, defined in \fB<curses.h>\fR,such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR..PPIf the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if theprogram is executing in a window environment, line and column information inthe environment will override information read by \fIterminfo\fR.  This wouldeffect a program running in an AT&T 630 layer, for example, where the size of ascreen is changeable (see \fBENVIRONMENT\fR)..PPIf the environment variable \fBTERMINFO\fR is defined, any program using\fBcurses\fR checks for a local terminal definition before checking in thestandard place.  For example, if \fBTERM\fR is set to \fBatt4424\fR, then thecompiled terminal definition is found in.sp      \fB\*d/a/att4424\fR..sp(The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoidcreation of huge directories.)  However, if \fBTERMINFO\fR is set to\fB$HOME/myterms\fR, \fBcurses\fR first checks.sp      \fB$HOME/myterms/a/att4424\fR,.spand if that fails, it then checks.sp      \fB\*d/a/att4424\fR..spThis is useful for developing experimental definitions or when writepermission in \fB\*d\fR is not available..PPThe integer variables \fBLINES\fR and \fBCOLS\fR are defined in\fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of thescreen.  The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and\fB0\fR, respectively..PPThe \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fRwhich is used for certain low-level operations like clearing and redrawing ascreen containing garbage.  The \fBcurscr\fR can be used in only a fewroutines...SS Routine and Argument NamesMany \fBcurses\fR routines have two or more versions.  The routines prefixedwith \fBw\fR require a window argument.  The routines prefixed with \fBp\fRrequire a pad argument.  Those without a prefix generally use \fBstdscr\fR..PPThe routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fRcoordinate to move to before performing the appropriate action.  The\fBmv\fR routines imply a call to \fBmove\fR before the call to theother routine.  The coordinate \fIy\fR always refers to the row (ofthe window), and \fIx\fR always refers to the column.  The upperleft-hand corner is always (0,0), not (1,1)..PPThe routines prefixed with \fBmvw\fR take both a window argument and\fIx\fR and \fIy\fR coordinates.  The window argument is alwaysspecified before the coordinates..PPIn each case, \fIwin\fR is the window affected, and \fIpad\fR is thepad affected; \fIwin\fR and \fIpad\fR are always pointers to type\fBWINDOW\fR..PPOption setting routines require a Boolean flag \fIbf\fR with the value\fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.  Thevariables \fIch\fR and \fIattrs\fR below are always of type\fBchtype\fR.  The types \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and\fBchtype\fR are defined in \fB<curses.h>\fR.  The type \fBTERMINAL\fRis defined in \fB<term.h>\fR.  All other arguments are integers..SS Routine Name IndexThe following table lists each \fBcurses\fR routine and the name ofthe manual page on which it is described.  Routines flagged with `*'are ncurses-specific, not described by XPG4 or present in SVr4..PP.TScenter tab(/);l ll l .\fBcurses\fR Routine Name/Manual Page Name=COLOR_PAIR/\fBcurs_color\fR(3X)PAIR_NUMBER/\fBcurs_attr\fR(3X)_nc_tracebits/\fBcurs_trace\fR(3X)*_traceattr/\fBcurs_trace\fR(3X)*_traceattr2/\fBcurs_trace\fR(3X)*_tracechar/\fBcurs_trace\fR(3X)*_tracechtype/\fBcurs_trace\fR(3X)*_tracechtype2/\fBcurs_trace\fR(3X)*_tracedump/\fBcurs_trace\fR(3X)*_tracef/\fBcurs_trace\fR(3X)*_tracemouse/\fBcurs_trace\fR(3X)*add_wch/\fBcurs_add_wch\fR(3X)add_wchnstr/\fBcurs_add_wchstr\fR(3X)add_wchstr/\fBcurs_add_wchstr\fR(3X)addch/\fBcurs_addch\fR(3X)addchnstr/\fBcurs_addchstr\fR(3X)addchstr/\fBcurs_addchstr\fR(3X)addnstr/\fBcurs_addstr\fR(3X)addnwstr/\fBcurs_addwstr\fR(3X)addstr/\fBcurs_addstr\fR(3X)addwstr/\fBcurs_addwstr\fR(3X)assume_default_colors/\fBdefault_colors\fR(3X)*attr_get/\fBcurs_attr\fR(3X)attr_off/\fBcurs_attr\fR(3X)attr_on/\fBcurs_attr\fR(3X)attr_set/\fBcurs_attr\fR(3X)attroff/\fBcurs_attr\fR(3X)attron/\fBcurs_attr\fR(3X)attrset/\fBcurs_attr\fR(3X)baudrate/\fBcurs_termattrs\fR(3X)beep/\fBcurs_beep\fR(3X)bkgd/\fBcurs_bkgd\fR(3X)bkgdset/\fBcurs_bkgd\fR(3X)bkgrnd/\fBcurs_bkgrnd\fR(3X)bkgrndset/\fBcurs_bkgrnd\fR(3X)border/\fBcurs_border\fR(3X)border_set/\fBcurs_border_set\fR(3X)box/\fBcurs_border\fR(3X)box_set/\fBcurs_border_set\fR(3X)can_change_color/\fBcurs_color\fR(3X)cbreak/\fBcurs_inopts\fR(3X)chgat/\fBcurs_attr\fR(3X)clear/\fBcurs_clear\fR(3X)clearok/\fBcurs_outopts\fR(3X)clrtobot/\fBcurs_clear\fR(3X)clrtoeol/\fBcurs_clear\fR(3X)color_content/\fBcurs_color\fR(3X)color_set/\fBcurs_attr\fR(3X)copywin/\fBcurs_overlay\fR(3X)curs_set/\fBcurs_kernel\fR(3X)curses_version/\fBcurs_extend\fR(3X)*def_prog_mode/\fBcurs_kernel\fR(3X)def_shell_mode/\fBcurs_kernel\fR(3X)define_key/\fBdefine_key\fR(3X)*del_curterm/\fBcurs_terminfo\fR(3X)delay_output/\fBcurs_util\fR(3X)delch/\fBcurs_delch\fR(3X)deleteln/\fBcurs_deleteln\fR(3X)delscreen/\fBcurs_initscr\fR(3X)delwin/\fBcurs_window\fR(3X)derwin/\fBcurs_window\fR(3X)doupdate/\fBcurs_refresh\fR(3X)dupwin/\fBcurs_window\fR(3X)echo/\fBcurs_inopts\fR(3X)echo_wchar/\fBcurs_add_wch\fR(3X)echochar/\fBcurs_addch\fR(3X)endwin/\fBcurs_initscr\fR(3X)erase/\fBcurs_clear\fR(3X)erasechar/\fBcurs_termattrs\fR(3X)erasewchar/\fBcurs_termattrs\fR(3X)filter/\fBcurs_util\fR(3X)flash/\fBcurs_beep\fR(3X)flushinp/\fBcurs_util\fR(3X)get_wch/\fBcurs_get_wch\fR(3X)get_wstr/\fBcurs_get_wstr\fR(3X)getbegyx/\fBcurs_getyx\fR(3X)getbkgd/\fBcurs_bkgd\fR(3X)getbkgrnd/\fBcurs_bkgrnd\fR(3X)getcchar/\fBcurs_getcchar\fR(3X)getch/\fBcurs_getch\fR(3X)getmaxyx/\fBcurs_getyx\fR(3X)getmouse/\fBcurs_mouse\fR(3X)*getn_wstr/\fBcurs_get_wstr\fR(3X)getnstr/\fBcurs_getstr\fR(3X)getparyx/\fBcurs_getyx\fR(3X)getstr/\fBcurs_getstr\fR(3X)getsyx/\fBcurs_kernel\fR(3X)getwin/\fBcurs_util\fR(3X)getyx/\fBcurs_getyx\fR(3X)halfdelay/\fBcurs_inopts\fR(3X)has_colors/\fBcurs_color\fR(3X)has_ic/\fBcurs_termattrs\fR(3X)has_il/\fBcurs_termattrs\fR(3X)has_key/\fBcurs_getch\fR(3X)*hline/\fBcurs_border\fR(3X)hline_set/\fBcurs_border_set\fR(3X)idcok/\fBcurs_outopts\fR(3X)idlok/\fBcurs_outopts\fR(3X)immedok/\fBcurs_outopts\fR(3X)in_wch/\fBcurs_in_wch\fR(3X)in_wchnstr/\fBcurs_in_wchstr\fR(3X)in_wchstr/\fBcurs_in_wchstr\fR(3X)inch/\fBcurs_inch\fR(3X)inchnstr/\fBcurs_inchstr\fR(3X)inchstr/\fBcurs_inchstr\fR(3X)init_color/\fBcurs_color\fR(3X)