curses(3X) DG/UX 5.4R3.00 curses(3X)
NAME
curses - CRT screen handling and optimization package
SYNOPSIS
#include <curses.h>
DESCRIPTION
The curses 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 -lcurses
option of cc.
The curses package allows: overall screen, window and pad
manipulation; output to windows and pads; reading terminal input;
control over terminal and curses input and output options;
environment query routines; color manipulation; use of soft label
keys; terminfo access; and access to low-level curses routines.
To initialize the routines, the routine initscr or newterm must be
called before any of the other routines that deal with windows and
screens are used. The routine endwin 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:
initscr,cbreak,noecho;
Most programs would additionally use the sequence:
nonl,intrflush(stdscr,FALSE),keypad(stdscr,TRUE);
Before a curses 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 tput init command after the shell
environment variable TERM has been exported. [See terminfo(4) for
further details.]
The curses library permits manipulation of data structures, called
windows, which can be thought of as two-dimensional arrays of
characters representing all or part of a CRT screen. A default
window called stdscr, which is the size of the terminal screen, is
supplied. Others may be created with newwin.
Windows are referred to by variables declared as WINDOW *. These
data structures are manipulated with routines described on 3X pages
(whose names begin "curs_"). Among the most basic routines are move
and addch. More general versions of these routines are included with
names beginning with w, allowing the user to specify a window. The
routines not beginning with w affect stdscr.
After using routines to manipulate a window, refresh is called,
telling curses to make the user's CRT screen look like stdscr. The
characters in a window are actually of type chtype, (character and
attribute data) so that other information about the character may
also be stored with each character.
Special windows called pads may also be manipulated. These are
Licensed material--property of copyright holder(s) 1
curses(3X) DG/UX 5.4R3.00 curses(3X)
windows which are not constrained to the size of the screen and whose
contents need not be completely displayed. See curspad(3X) for more
information.
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, curses 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 <curses.h>, such as AREVERSE,
ACSHLINE, and KEYLEFT.
If the environment variables LINES and COLUMNS are set, or if the
program is executing in a window environment, line and column
information in the environment will override information read by
terminfo. This would effect a program running in an AT&T 630 layer,
for example, where the size of a screen is changeable.
If the environment variable TERMINFO is defined, any program using
curses checks for a local terminal definition before checking in the
standard place. For example, if TERM is set to att4424, then the
compiled terminal definition is found in
/usr/share/lib/terminfo/a/att4424.
(The a is copied from the first letter of att4424 to avoid creation
of huge directories.) However, if TERMINFO is set to $HOME/myterms,
curses first checks
$HOME/myterms/a/att4424,
and if that fails, it then checks
/usr/share/lib/terminfo/a/att4424.
This is useful for developing experimental definitions or when write
permission in /usr/share/lib/terminfo is not available.
The integer variables LINES and COLS are defined in <curses.h> and
will be filled in by initscr with the size of the screen. The
constants TRUE and FALSE have the values 1 and 0, respectively.
The curses routines also define the WINDOW * variable curscr which is
used for certain low-level operations like clearing and redrawing a
screen containing garbage. The curscr can be used in only a few
routines.
International Functions
In addition to the standard curses library, the curses32 library is
available for handling multibyte characters in 32 bit process code.
The curses32 library provides additional functions, as well as
enhancements to existing curses library functions. This section
describes characteristics of the curses32 library. A program using
the curses32 library functions must be compiled with the -lcurses32
option of cc.
The number of bytes and the number of columns to hold a character
from a supplementary character set is locale-specific (locale
Licensed material--property of copyright holder(s) 2
curses(3X) DG/UX 5.4R3.00 curses(3X)
category LCCTYPE) and can be specified in the character class table.
For editing, operating at the character level is entirely
appropriate. For screen formatting, arbitrary movement of characters
on the screen is not desirable.
Overwriting characters (for example, addch) operates on a screen
level. Overwriting a character by a character which requires a
different number of columns may produce orphaned columns. These
orphaned columns are filled with the background character.
Inserting characters (for example, insch) operates on a character
level (that is, at the character boundaries). The specified
character is inserted right before the character, regardless of
whichever column of a character the cursor points to. Before
insertion, the cursor position is adjusted to the first column of the
character.
As with inserting characters, deleting characters (for example,
delch) operates on a character level (that is, at the character
boundaries). The character at the cursor is deleted regardless of
whichever columns of the character the cursor points to. Before
deletion, the cursor position is adjusted to the first column of the
character.
Multi-column characters cannot be put on the last column of lines.
When such attempts are made, the last column is set to the background
character. In addition, when such an operation creates orphaned
columns, the columns are also filled with the background character.
Overlapping and overwriting windows follows the operation of
overwriting characters around its edge. The orphaned columns, if
any, are handled in the same manner as the character operations.
The cursor is allowed to be placed anywhere in a window. If the
insertion or deletion is made when the cursor points to the second or
later column position of a character which holds multiple columns,
the cursor is adjusted to the first column of it before the insertion
or deletion.
Routine and Argument Names
Many curses routines have two or more versions. The routines
prefixed with w require a window argument. The routines prefixed
with p require a pad argument. Those without a prefix generally use
stdscr.
The routines prefixed with mv require an x and y coordinate to move
to before performing the appropriate action. The mv routines imply a
call to move before the call to the other routine. The coordinate y
always refers to the row (of the window), and x always refers to the
column. The upper left-hand corner is always (0,0), not (1,1).
The routines prefixed with mvw take both a window argument and x and
y coordinates. The window argument is always specified before the
Licensed material--property of copyright holder(s) 3
curses(3X) DG/UX 5.4R3.00 curses(3X)
coordinates.
In each case, win is the window affected, and pad is the pad
affected; win and pad are always pointers to type WINDOW.
Option setting routines require a Boolean flag bf with the value TRUE
or FALSE; bf is always of type bool. The variables ch and attrs
below are always of type chtype. The types WINDOW, SCREEN, bool, and
chtype are defined in <curses.h>. The type TERMINAL is defined in
<term.h>. All other arguments are integers.
Routine Name Index
The following table lists each curses routine and the name of the
manual page on which it is described. The routines marked with an "*"
provide new or enhanced function in the curses32 library.
curses Routine Name Manual Page Name
--------------------------------------------
addch cursaddch(3X)
addchnstr cursaddchstr(3X)
addchstr cursaddchstr(3X)
addnstr cursaddstr(3X)
*addnwstr cursaddwstr(3X)
addstr cursaddstr(3X)
*addwch cursaddwch(3X)
*addwchnstr cursaddwchstr(3X)
*addwchstr cursaddwchstr(3X)
*addwstr cursaddwstr(3X)
attroff cursattr(3X)
attron cursattr(3X)
attrset cursattr(3X)
baudrate curstermattrs(3X)
beep cursbeep(3X)
bkgd cursbkgd(3X)
bkgdset cursbkgd(3X)
border cursborder(3X)
box cursborder(3X)
canchangecolor curscolor(3X)
cbreak cursinopts(3X)
clear cursclear(3X)
clearok cursoutopts(3X)
clrtobot cursclear(3X)
clrtoeol cursclear(3X)
colorcontent curscolor(3X)
copywin cursoverlay(3X)
cursset curskernel(3X)
defprogmode curskernel(3X)
defshellmode curskernel(3X)
delcurterm cursterminfo(4)
delayoutput cursutil(3X)
*delch cursdelch(3X)
deleteln cursdeleteln(3X)
delscreen cursinitscr(3X)
delwin curswindow(3X)
Licensed material--property of copyright holder(s) 4
curses(3X) DG/UX 5.4R3.00 curses(3X)
derwin curswindow(3X)
doupdate cursrefresh(3X)
dupwin curswindow(3X)
echo cursinopts(3X)
echochar cursaddch(3X)
*echowchar cursaddwch(3X)
endwin cursinitscr(3X)
erase cursclear(3X)
erasechar curstermattrs(3X)
filter cursutil(3X)
flash cursbeep(3X)
flushinp cursutil(3X)
getbegyx cursgetyx(3X)
getch cursgetch(3X)
getmaxyx cursgetyx(3X)
*getnwstr cursgetwstr(3X)
getparyx cursgetyx(3X)
getstr cursgetstr(3X)
getsyx curskernel(3X)
*getwch cursgetwch(3X)
getwin cursutil(3X)
*getwstr cursgetwstr(3X)
getyx cursgetyx(3X)
halfdelay cursinopts(3X)
hascolors curscolor(3X)
hasic curstermattrs(3X)
hasil curstermattrs(3X)
idcok cursoutopts(3X)
idlok cursoutopts(3X)
immedok cursoutopts(3X)
inch cursinch(3X)
inchnstr cursinchstr(3X)
inchstr cursinchstr(3X)
initcolor curscolor(3X)
initpair curscolor(3X)
initscr cursinitscr(3X)
innstr cursinstr(3X)
*innwstr cursinwstr(3X)
insch cursinsch(3X)
insdelln cursdeleteln(3X)
insertln cursdeleteln(3X)
insnstr cursinsstr(3X)
*insnwstr cursinswstr(3X)
insstr cursinsstr(3X)
instr cursinstr(3X)
*inswch cursinswch(3X)
*inswstr cursinswstr(3X)
intrflush cursinopts(3X)
*inwch cursinwch(3X)
*inwchnstr cursinwchstr(3X)
*inwchstr cursinwchstr(3X)
*inwstr cursinwstr(3X)
islinetouched curstouch(3X)
Licensed material--property of copyright holder(s) 5
curses(3X) DG/UX 5.4R3.00 curses(3X)
iswintouched curstouch(3X)
isendwin cursinitscr(3X)
keyname cursutil(3X)
keypad cursinopts(3X)
killchar curstermattrs(3X)
leaveok cursoutopts(3X)
longname curstermattrs(3X)
meta cursinopts(3X)
move cursmove(3X)
mvaddch cursaddch(3X)
mvaddchnstr cursaddchstr(3X)
mvaddchstr cursaddchstr(3X)
mvaddnstr cursaddstr(3X)
*mvaddnwstr cursaddwstr(3X)
mvaddstr cursaddstr(3X)
*mvaddwch cursaddwch(3X)
*mvaddwchnstr cursaddwchstr(3X)
*mvaddwchstr cursaddwchstr(3X)
*mvaddwstr cursaddwstr(3X)
mvcur cursterminfo(4)
*mvdelch cursdelch(3X)
mvderwin curswindow(3X)
mvgetch cursgetch(3X)
*mvgetnwstr cursgetwstr(3X)
mvgetstr cursgetstr(3X)
*mvgetwch cursgetwch(3X)
*mvgetwstr cursgetwstr(3X)
mvinch cursinch(3X)
mvinchnstr cursinchstr(3X)
mvinchstr cursinchstr(3X)
mvinnstr cursinstr(3X)
*mvinnwstr cursinwstr(3X)
mvinsch cursinsch(3X)
mvinsnstr cursinsstr(3X)
*mvinsnwstr cursinswstr(3X)
mvinsstr cursinsstr(3X)
mvinstr cursinstr(3X)
*mvinswch cursinswch(3X)
*mvinswstr cursinswstr(3X)
*mvinwch cursinwch(3X)
*mvinwchnstr cursinwchstr(3X)
*mvinwchstr cursinwchstr(3X)
*mvinwstr cursinwstr(3X)
*mvprintw cursprintw(3X)
*mvscanw cursscanw(3X)
mvwaddch cursaddch(3X)
mvwaddchnstr cursaddchstr(3X)
mvwaddchstr cursaddchstr(3X)
mvwaddnstr cursaddstr(3X)
*mvwaddnwstr cursaddwstr(3X)
mvwaddstr cursaddstr(3X)
*mvwaddwch cursaddwch(3X)
*mvwaddwchnstr cursaddwchstr(3X)
Licensed material--property of copyright holder(s) 6
curses(3X) DG/UX 5.4R3.00 curses(3X)
*mvwaddwchstr cursaddwchstr(3X)
*mvwaddwstr cursaddwstr(3X)
*mvwdelch cursdelch(3X)
mvwgetch cursgetch(3X)
*mvwgetnwstr cursgetwstr(3X)
mvwgetstr cursgetstr(3X)
*mvwgetwch cursgetwch(3X)
*mvwgetwstr cursgetwstr(3X)
mvwin curswindow(3X)
mvwinch cursinch(3X)
mvwinchnstr cursinchstr(3X)
mvwinchstr cursinchstr(3X)
mvwinnstr cursinstr(3X)
*mvwinnwstr cursinwstr(3X)
mvwinsch cursinsch(3X)
mvwinsnstr cursinsstr(3X)
*mvwinsnwstr cursinswstr(3X)
mvwinsstr cursinsstr(3X)
mvwinstr cursinstr(3X)
*mvwinswch cursinswch(3X)
*mvwinswstr cursinswstr(3X)
*mvwinwch cursinwch(3X)
*mvwinwchnstr cursinwchstr(3X)
*mvwinwchstr cursinwchstr(3X)
*mvwinwstr cursinwstr(3X)
*mvwprintw cursprintw(3X)
*mvwscanw cursscanw(3X)
napms curskernel(3X)
newpad curspad(3X)
newterm cursinitscr(3X)
newwin curswindow(3X)
nl cursoutopts(3X)
nocbreak cursinopts(3X)
nodelay cursinopts(3X)
noecho cursinopts(3X)
nonl cursoutopts(3X)
noqiflush cursinopts(3X)
noraw cursinopts(3X)
notimeout cursinopts(3X)
overlay cursoverlay(3X)
overwrite cursoverlay(3X)
paircontent curscolor(3X)
pechochar curspad(3X)
*pechowchar curspad(3X)
pnoutrefresh curspad(3X)
prefresh curspad(3X)
*printw cursprintw(3X)
putp cursterminfo(4)
putwin cursutil(3X)
qiflush cursinopts(3X)
raw cursinopts(3X)
redrawwin cursrefresh(3X)
refresh cursrefresh(3X)
Licensed material--property of copyright holder(s) 7
curses(3X) DG/UX 5.4R3.00 curses(3X)
resetprogmode curskernel(3X)
resetshellmode curskernel(3X)
resetty curskernel(3X)
restartterm cursterminfo(4)
ripoffline curskernel(3X)
savetty curskernel(3X)
*scanw cursscanw(3X)
scrdump cursscrdump(3X)
scrinit cursscrdump(3X)
scrrestore cursscrdump(3X)
scrset cursscrdump(3X)
scrl cursscroll(3X)
scroll cursscroll(3X)
scrollok cursoutopts(3X)
setcurterm cursterminfo(4)
setterm cursinitscr(3X)
setscrreg cursoutopts(3X)
setsyx curskernel(3X)
setterm cursterminfo(4)
setupterm cursterminfo(4)
slkattroff cursslk(3X)
slkattron cursslk(3X)
slkattrset cursslk(3X)
slkclear cursslk(3X)
slkinit cursslk(3X)
slklabel cursslk(3X)
slknoutrefresh cursslk(3X)
slkrefresh cursslk(3X)
slkrestore cursslk(3X)
slkset cursslk(3X)
slktouch cursslk(3X)
standend cursattr(3X)
standout cursattr(3X)
startcolor curscolor(3X)
subpad curspad(3X)
subwin curswindow(3X)
syncok curswindow(3X)
termattrs curstermattrs(3X)
termname curstermattrs(3X)
tgetent curstermcap(3X)
tgetflag curstermcap(3X)
tgetnum curstermcap(3X)
tgetstr curstermcap(3X)
tgoto curstermcap(3X)
tigetflag cursterminfo(4)
tigetnum cursterminfo(4)
tigetstr cursterminfo(4)
timeout cursinopts(3X)
touchline curstouch(3X)
touchwin curstouch(3X)
tparm cursterminfo(4)
tputs curstermcap(3X)
tputs cursterminfo(4)
Licensed material--property of copyright holder(s) 8
curses(3X) DG/UX 5.4R3.00 curses(3X)
typeahead cursinopts(3X)
unctrl cursutil(3X)
ungetch cursgetch(3X)
*ungetwch cursgetwch(3X)
untouchwin curstouch(3X)
useenv cursutil(3X)
vidattr cursterminfo(4)
vidputs cursterminfo(4)
vwprintw cursprintw(3X)
vwscanw cursscanw(3X)
waddch cursaddch(3X)
waddchnstr cursaddchstr(3X)
waddchstr cursaddchstr(3X)
waddnstr cursaddstr(3X)
*waddnwstr cursaddwstr(3X)
waddstr cursaddstr(3X)
*waddwch cursaddwch(3X)
*waddwchnstr cursaddwchstr(3X)
*waddwchstr cursaddwchstr(3X)
*waddwstr cursaddwstr(3X)
wattroff cursattr(3X)
wattron cursattr(3X)
wattrset cursattr(3X)
wbkgd cursbkgd(3X)
wbkgdset cursbkgd(3X)
wborder cursborder(3X)
wclear cursclear(3X)
wclrtobot cursclear(3X)
wclrtoeol cursclear(3X)
wcursyncup curswindow(3X)
*wdelch cursdelch(3X)
wdeleteln cursdeleteln(3X)
wechochar cursaddch(3X)
*wechowchar cursaddwch(3X)
werase cursclear(3X)
wgetch cursgetch(3X)
wgetnstr cursgetstr(3X)
*wgetnwstr cursgetwstr(3X)
wgetstr cursgetstr(3X)
*wgetwch cursgetwch(3X)
*wgetwstr cursgetwstr(3X)
whline cursborder(3X)
winch cursinch(3X)
winchnstr cursinchstr(3X)
winchstr cursinchstr(3X)
winnstr cursinstr(3X)
*winnwstr cursinwstr(3X)
winsch cursinsch(3X)
winsdelln cursdeleteln(3X)
winsertln cursdeleteln(3X)
winsnstr cursinsstr(3X)
*winsnwstr cursinswstr(3X)
winsstr cursinsstr(3X)
Licensed material--property of copyright holder(s) 9
curses(3X) DG/UX 5.4R3.00 curses(3X)
winstr cursinstr(3X)
*winswch cursinswch(3X)
*winswstr cursinswstr(3X)
*winwch cursinwch(3X)
*winwchnstr cursinwchstr(3X)
*winwchstr cursinwchstr(3X)
*winwstr cursinwstr(3X)
wmove cursmove(3X)
wnoutrefresh cursrefresh(3X)
*wprintw cursprintw(3X)
wredrawln cursrefresh(3X)
wrefresh cursrefresh(3X)
*wscanw cursscanw(3X)
wscrl cursscroll(3X)
wsetscrreg cursoutopts(3X)
wstandend cursattr(3X)
wstandout cursattr(3X)
wsyncdown curswindow(3X)
wsyncup curswindow(3X)
wtimeout cursinopts(3X)
wtouchln curstouch(3X)
wvline cursborder(3X)
RETURN VALUE
Routines that return an integer return ERR upon failure and an
integer value other than ERR upon successful completion, unless
otherwise noted in the routine descriptions.
All macros return the value of the w version, except setscrreg,
wsetscrreg, getyx, getbegyx, getmaxyx. The return values of
setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx are undefined
(that is, these should not be used as the right-hand side of
assignment statements).
Routines that return pointers return NULL on error.
SEE ALSO
terminfo(4) and 3X pages whose names begin "curs_" for detailed
routine descriptions.
cursaddch(3X), cursaddchstr(3X), cursaddstr(3X), cursattr(3X),
cursbeep(3X), cursbkgd(3X), cursborder(3X), cursclear(3X),
curscolor(3X), cursdelch(3X), cursdeleteln(3X), cursgetch(3X),
cursgetyx(3X), cursinch(3X), cursinchstr(3X), cursinitscr(3X),
cursinopts(3X), cursinsch(3X), cursinsstr(3X), cursinstr(3X),
curskernel(3X), cursmove(3X), cursoutopts(3X), cursoverlay(3X),
cursrefresh(3X), cursscroll(3X), cursslk(3X), curstermattrs(3X),
curstermcap(3X), cursterminfo(3X), curstouch(3X), cursutil(3X),
curswindow(3X) in the System V Release 4.0 Programmer's Guide:
Character User Interface.
NOTES
The header file <curses.h> automatically includes the header files
<stdio.h> and <unctrl.h>.
Licensed material--property of copyright holder(s) 10