'\"! tbl | mmdoc
'\"macro stdmacro
.if n .pH g3x.curses @(#)curses	40.4 of 12/15/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} curses 3X "Terminal Information Utilities" "\&"
.if \nX=1 .ds x} curses 3X "Terminal Information Utilities"
.if \nX=2 .ds x} curses 3X "" "\&"
.if \nX=3 .ds x} curses "" "" "\&"
.TH \*(x}
'\" ident	"@(#)svid_ti:ti_env/curses	1.6"
.if n .pH ti_lib.curses @(#)curses	30.1
.SH NAME
\f4curses\fP \- CRT screen handling and optimization package
.SH SYNOPSIS
.ft 4
#include <curses.h>
.ft 1
.SH DESCRIPTION
The \f4curses\f1 library routines give the user a terminal-independent
method of updating character screens with reasonable optimization.
A program using these routines must be compiled with
the \f4\-lcurses\f1 option of \f4cc\f1.
.P
The \f4curses\fP package allows:  overall screen, window and pad manipulation;
output to windows and pads; reading terminal input; control over terminal
and \f4curses\fP input and output options; environment query routines;
color manipulation; use of soft label keys; terminfo access; and
access to low-level \f4curses\fP routines.
.P
To initialize the routines, the routine \f4initscr\f1 or \f4newterm\f1
must be called before any of the other routines that deal with windows
and screens are used.
The routine \f4endwin\f1 must be called before exiting.
To get character-at-a-time input without echoing
(most interactive, screen oriented programs want this),
the following sequence should be used:
.RS
\f4initscr,cbreak,noecho;\f1
.RE
Most programs would additionally use the sequence:
.RS
\f4nonl,intrflush(stdscr,FALSE),keypad(stdscr,TRUE);\f1
.RE
.P
Before a \f4curses\fP program is run, the tab stops of the terminal should be set
and its initialization strings, if defined, must be output.
This can be done by executing the \f4tput init\f1
command after the shell environment variable \f4TERM\f1 
has been exported.
[See \f4terminfo\fP(4) for further details.]
.P
The \f4curses\fP library permits manipulation of data structures,
called \f2windows\f1,
which can be thought of as two-dimensional arrays of characters
representing all or part of a CRT screen.
A default window called \f4stdscr\f1,
which is the size of the terminal screen, is supplied.
Others may be created with \f4newwin\f1.
.PP
Windows are referred to by variables declared as \f4WINDOW *\f1.
These data structures are manipulated with routines described on 3X
paages (whose names begin "curs_").
Among which the most basic routines are \f4move\f1 and \f4addch\f1.
More general versions of these routines are included with names
beginning with \f4w\f1, allowing the user to specify a window.
The routines not beginning with \f4w\f1 affect \f4stdscr\f1.)\f1
.PP
After using routines to manipulate a window, \f4refresh\f1 is called,
telling \f4curses\fP to make the user's CRT screen look like \f4stdscr\f1.
The characters in a window are actually of type \f4chtype\f1,
(character and attribute data) so that other information about the
character may also be stored with each character.
.P
Special windows called \f2pads\f1 may also be manipulated.
These are windows which are not constrained to the size of the
screen and whose contents need not be completely displayed.
See curs_pad(3X) for more information.
.P
In addition to drawing characters on the screen, video attributes and colors
may be included, causing the characters to show up in such
modes as underlined, in reverse video, or in color on terminals that support
such display enhancements.
Line drawing characters may be specified to be output.
On input, \f4curses\fP is also able to translate arrow and function
keys that transmit escape sequences into single values.
The video attributes, line drawing characters, and input values use names,
defined in \f4<curses.h>\f1, 
such as \f4A_REVERSE\f1, \f4ACS_HLINE\f1, and \f4KEY_LEFT\f1.
.P
If the environment variables \f4LINES\f1 and \f4COLUMNS\f1 are set,
or if the program is executing in a window environment, line and column
information in the environment will override information read by
\f2terminfo\f1.
This would effect a program running in an AT&T 630 layer, for example, where
the size of a screen is changeable.
.P
If the environment variable \f4TERMINFO\f1 is defined, any program
using \f4curses\fP checks for a local terminal definition before
checking in the standard place.
For example, if \f4TERM\fP is set to \f4att4424\f1,
then the compiled terminal definition is found in
.RS
\f4/usr/share/lib/terminfo/a/att4424\f1.
.RE
(The \f4a\fP is copied from the first letter
of \f4att4424\fP to avoid creation of huge directories.)
However, if \f4TERMINFO\f1 is set to \f4$HOME/myterms\f1, \f4curses\fP
first checks
.RS
\f4$HOME/myterms/a/att4424\f1,
.RE
and if that fails, it then checks
.RS
\f4/usr/share/lib/terminfo/a/att4424\f1.
.RE
This is useful for developing experimental definitions or
when write permission in \f4/usr/share/lib/terminfo\f1 is not available.
.P
The integer variables \f4LINES\f1 and \f4COLS\f1 are defined in
\f4<curses.h>\f1
and will be filled in by \f4initscr\f1 with the size of the screen.
The constants \f4TRUE\f1 and \f4FALSE\f1 have the values
\f41\f1 and \f40\f1, respectively.
.P
The \f4curses\fP routines also define the \f4WINDOW *\f1 variable \f4curscr\f1
which is used for certain low-level operations like clearing and
redrawing a screen containing garbage.
The \f4curscr\f1 can be used in only a few routines.
.SS Routine and Argument Names
Many \f4curses\fP routines have two or more versions.
The routines prefixed with \f4w\f1 require a window argument.
The routines prefixed with \f4p\f1 require a pad argument.
Those without a prefix generally use \f4stdscr\f1.
.P
The routines prefixed with \f4mv\f1 require an \f2x\f1 and \f2y\f1
coordinate to move to before performing the appropriate action.
The \f4mv\f1 routines imply a call to \f4move\f1
before the call to the other routine.
The coordinate \f2y\f1 always refers to the row (of the window),
and \f2x\f1 always refers to the column.
The upper left-hand corner is always (0,0), not (1,1).
.P
The routines prefixed with \f4mvw\f1 take both a
window argument and \f2x\f1 and \f2y\f1 coordinates.
The window argument is always specified before the coordinates.
.P
In each case, \f2win\f1 is the window affected, and \f2pad\f1
is the pad affected;
\f2win\f1 and \f2pad\f1 are always pointers to type \f4WINDOW\f1.
.PP
Option setting routines require a Boolean flag \f2bf\f1
with the value \f4TRUE\f1 or \f4FALSE\f1;
\f2bf\f1 is always of type \f4bool\f1.
The variables \f2ch\f1 and \f2attrs\f1 below are always of type
\f4chtype\f1.
The types \f4WINDOW\f1, \f4SCREEN\fP, \f4bool\f1, and \f4chtype\f1
are defined in \f4<curses.h>\f1.
The type \f4TERMINAL\fP is defined in \f4<term.h>\fP.
All other arguments are integers.
.SS Routine Name Index
The following table lists each \f4curses\fP routine and the name of the
manual page on which it is described.
.TS H
lfHB lfHB
lfCWw(2i) lw(2i).
\f4curses\fP Routine Name	Manual Page Name
.sp 0.5
_
.TH
addch	curs_addch(3X)
addchnstr	curs_addchstr(3X)
addchstr	curs_addchstr(3X)
addnstr	curs_addstr(3X)
addstr	curs_addstr(3X)
attroff	curs_attr(3X)
attron	curs_attr(3X)
attrset	curs_attr(3X)
baudrate	curs_termattrs(3X)
beep	curs_beep(3X)
bkgd	curs_bkgd(3X)
bkgdset	curs_bkgd(3X)
border	curs_border(3X)
box	curs_border(3X)
can_change_color	curs_color(3X)
cbreak	curs_inopts(3X)
clear	curs_clear(3X)
clearok	curs_outopts(3X)
clrtobot	curs_clear(3X)
clrtoeol	curs_clear(3X)
color_content	curs_color(3X)
copywin	curs_overlay(3X)
curs_set	curs_kernel(3X)
def_prog_mode	curs_kernel(3X)
def_shell_mode	curs_kernel(3X)
del_curterm	curs_\f4terminfo\fP(4)
delay_output	curs_util(3X)
delch	curs_delch(3X)
deleteln	curs_deleteln(3X)
delscreen	curs_initscr(3X)
delwin	curs_window(3X)
derwin	curs_window(3X)
doupdate	curs_refresh(3X)
dupwin	curs_window(3X)
echo	curs_inopts(3X)
echochar	curs_addch(3X)
endwin	curs_initscr(3X)
erase	curs_clear(3X)
erasechar	curs_termattrs(3X)
filter	curs_util(3X)
flash	curs_beep(3X)
flushinp	curs_util(3X)
getbegyx	curs_getyx(3X)
getch	curs_getch(3X)
getmaxyx	curs_getyx(3X)
getparyx	curs_getyx(3X)
getstr	curs_getstr(3X)
getsyx	curs_kernel(3X)
getwin	curs_util(3X)
getyx	curs_getyx(3X)
halfdelay	curs_inopts(3X)
has_colors	curs_color(3X)
has_ic	curs_termattrs(3X)
has_il	curs_termattrs(3X)
idcok	curs_outopts(3X)
idlok	curs_outopts(3X)
immedok	curs_outopts(3X)
inch	curs_inch(3X)
inchnstr	curs_inchstr(3X)
inchstr	curs_inchstr(3X)
init_color	curs_color(3X)
init_pair	curs_color(3X)
initscr	curs_initscr(3X)
innstr	curs_instr(3X)
insch	curs_insch(3X)
insdelln	curs_deleteln(3X)
insertln	curs_deleteln(3X)
insnstr	curs_insstr(3X)
insstr	curs_insstr(3X)
instr	curs_instr(3X)
intrflush	curs_inopts(3X)
is_linetouched	curs_touch(3X)
is_wintouched	curs_touch(3X)
isendwin	curs_initscr(3X)
keyname	curs_util(3X)
keypad	curs_inopts(3X)
killchar	curs_termattrs(3X)
leaveok	curs_outopts(3X)
longname	curs_termattrs(3X)
meta	curs_inopts(3X)
move	curs_move(3X)
mvaddch	curs_addch(3X)
mvaddchnstr	curs_addchstr(3X)
mvaddchstr	curs_addchstr(3X)
mvaddnstr	curs_addstr(3X)
mvaddstr	curs_addstr(3X)
mvcur	curs_\f4terminfo\fP(4)
mvdelch	curs_delch(3X)
mvderwin	curs_window(3X)
mvgetch	curs_getch(3X)
mvgetstr	curs_getstr(3X)
mvinch	curs_inch(3X)
mvinchnstr	curs_inchstr(3X)
mvinchstr	curs_inchstr(3X)
mvinnstr	curs_instr(3X)
mvinsch	curs_insch(3X)
mvinsnstr	curs_insstr(3X)
mvinsstr	curs_insstr(3X)
mvinstr	curs_instr(3X)
mvprintw	curs_printw(3X)
mvscanw	curs_scanw(3X)
mvwaddch	curs_addch(3X)
mvwaddchnstr	curs_addchstr(3X)
mvwaddchstr	curs_addchstr(3X)
mvwaddnstr	curs_addstr(3X)
mvwaddstr	curs_addstr(3X)
mvwdelch	curs_delch(3X)
mvwgetch	curs_getch(3X)
mvwgetstr	curs_getstr(3X)
mvwin	curs_window(3X)
mvwinch	curs_inch(3X)
mvwinchnstr	curs_inchstr(3X)
mvwinchstr	curs_inchstr(3X)
mvwinnstr	curs_instr(3X)
mvwinsch	curs_insch(3X)
mvwinsnstr	curs_insstr(3X)
mvwinsstr	curs_insstr(3X)
mvwinstr	curs_instr(3X)
mvwprintw	curs_printw(3X)
mvwscanw	curs_scanw(3X)
napms	curs_kernel(3X)
newpad	curs_pad(3X)
newterm	curs_initscr(3X)
newwin	curs_window(3X)
nl	curs_outopts(3X)
nocbreak	curs_inopts(3X)
nodelay	curs_inopts(3X)
noecho	curs_inopts(3X)
nonl	curs_outopts(3X)
noqiflush	curs_inopts(3X)
noraw	curs_inopts(3X)
notimeout	curs_inopts(3X)
overlay	curs_overlay(3X)
overwrite	curs_overlay(3X)
pair_content	curs_color(3X)
pechochar	curs_pad(3X)
pnoutrefresh	curs_pad(3X)
prefresh	curs_pad(3X)
printw	curs_printw(3X)
putp	curs_\f4terminfo\fP(4)
putwin	curs_util(3X)
qiflush	curs_inopts(3X)
raw	curs_inopts(3X)
redrawwin	curs_refresh(3X)
refresh	curs_refresh(3X)
reset_prog_mode	curs_kernel(3X)
reset_shell_mode	curs_kernel(3X)
resetty	curs_kernel(3X)
restartterm	curs_\f4terminfo\fP(4)
ripoffline	curs_kernel(3X)
savetty	curs_kernel(3X)
scanw	curs_scanw(3X)
scr_dump	curs_scr_dump(3X)
scr_init	curs_scr_dump(3X)
scr_restore	curs_scr_dump(3X)
scr_set	curs_scr_dump(3X)
scroll	curs_scroll(3X)
scrollok	curs_outopts(3X)
set_curterm	curs_\f4terminfo\fP(4)
set_term	curs_initscr(3X)
setscrreg	curs_outopts(3X)
setsyx	curs_kernel(3X)
setterm	curs_\f4terminfo\fP(4)
setupterm	curs_\f4terminfo\fP(4)
slk_attroff	curs_slk(3X)
slk_attron	curs_slk(3X)
slk_attrset	curs_slk(3X)
slk_clear	curs_slk(3X)
slk_init	curs_slk(3X)
slk_label	curs_slk(3X)
slk_noutrefresh	curs_slk(3X)
slk_refresh	curs_slk(3X)
slk_restore	curs_slk(3X)
slk_set	curs_slk(3X)
slk_touch	curs_slk(3X)
srcl	curs_scroll(3X)
standend	curs_attr(3X)
standout	curs_attr(3X)
start_color	curs_color(3X)
subpad	curs_pad(3X)
subwin	curs_window(3X)
syncok	curs_window(3X)
termattrs	curs_termattrs(3X)
termname	curs_termattrs(3X)
tgetent	curs_termcap(3X)
tgetflag	curs_termcap(3X)
tgetnum	curs_termcap(3X)
tgetstr	curs_termcap(3X)
tgoto	curs_termcap(3X)
tigetflag	curs_\f4terminfo\fP(4)
tigetnum	curs_\f4terminfo\fP(4)
tigetstr	curs_\f4terminfo\fP(4)
timeout	curs_inopts(3X)
touchline	curs_touch(3X)
touchwin	curs_touch(3X)
tparm	curs_\f4terminfo\fP(4)
tputs	curs_termcap(3X)
tputs	curs_\f4terminfo\fP(4)
typeahead	curs_inopts(3X)
unctrl	curs_util(3X)
ungetch	curs_getch(3X)
untouchwin	curs_touch(3X)
use_env	curs_util(3X)
vidattr	curs_\f4terminfo\fP(4)
vidputs	curs_\f4terminfo\fP(4)
vwprintw	curs_printw(3X)
vwscanw	curs_scanw(3X)
waddch	curs_addch(3X)
waddchnstr	curs_addchstr(3X)
waddchstr	curs_addchstr(3X)
waddnstr	curs_addstr(3X)
waddstr	curs_addstr(3X)
wattroff	curs_attr(3X)
wattron	curs_attr(3X)
wattrset	curs_attr(3X)
wbkgd	curs_bkgd(3X)
wbkgdset	curs_bkgd(3X)
wborder	curs_border(3X)
wclear	curs_clear(3X)
wclrtobot	curs_clear(3X)
wclrtoeol	curs_clear(3X)
wcursyncup	curs_window(3X)
wdelch	curs_delch(3X)
wdeleteln	curs_deleteln(3X)
wechochar	curs_addch(3X)
werase	curs_clear(3X)
wgetch	curs_getch(3X)
wgetnstr	curs_getstr(3X)
wgetstr	curs_getstr(3X)
whline	curs_border(3X)
winch	curs_inch(3X)
winchnstr	curs_inchstr(3X)
winchstr	curs_inchstr(3X)
winnstr	curs_instr(3X)
winsch	curs_insch(3X)
winsdelln	curs_deleteln(3X)
winsertln	curs_deleteln(3X)
winsnstr	curs_insstr(3X)
winsstr	curs_insstr(3X)
winstr	curs_instr(3X)
wmove	curs_move(3X)
wnoutrefresh	curs_refresh(3X)
wprintw	curs_printw(3X)
wredrawln	curs_refresh(3X)
wrefresh	curs_refresh(3X)
wscanw	curs_scanw(3X)
wscrl	curs_scroll(3X)
wsetscrreg	curs_outopts(3X)
wstandend	curs_attr(3X)
wstandout	curs_attr(3X)
wsyncdown	curs_window(3X)
wsyncup	curs_window(3X)
wtimeout	curs_inopts(3X)
wtouchln	curs_touch(3X)
wvline	curs_border(3X)
.TE
.SH RETURN VALUE
Routines that return an integer return \f4ERR\f1 upon
failure and an integer value other than \f4ERR\f1
upon successful completion,
unless otherwise noted in the routine descriptions.
.P
All macros return the value of the \f4w\f1 version,
except \f4setscrreg\f1, \f4wsetscrreg\f1,
\f4getyx\f1, \f4getbegyx\f1, \f4getmaxyx\f1.
The return values of \f4setscrreg\f1, \f4wsetscrreg\f1,
\f4getyx\f1, \f4getbegyx\f1, and \f4getmaxyx\f1
are undefined (\f2i.e.\f1, these should not be used as the
right-hand side of assignment statements).
.P
Routines that return pointers return \f4NULL\f1 on error.
.SH SEE ALSO
.na
\f4terminfo\fP(4) and 3X pages whose names begin "curs_" for
detailed routine descriptions.
.ad
.SH NOTES
.P
The header file \f4<curses.h>\f1 automatically includes the header files
\f4<stdio.h>\f1 and \f4<unctrl.h>\f1.
