Curses Library Functions curses(3CURSES)
NAME
curses - CRT screen handling and optimization package
SYNOPSIS
cc [ flag... ] file.. .-lcurses [ library... ]
#include
DESCRIPTION
The curses library routines give the user a terminal-
independent method of updating character screens with rea-
sonable optimization.
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 termi-
nal 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
SunOS 5.11 Last change: 23 Oct 2001 1
Curses Library Functions curses(3CURSES)
newwin(3CURSES).
Windows are referred to by variables declared as WINDOW *.
These data structures are manipulated with routines
described on 3CURSES pages (whose names begin "curs").
Among which the most basic routines are move(3CURSES) and
addch(3CURSES). 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(3CURSES) is called, telling curses to make the
user's CRT screen look like stdscr. The characters in a win-
dow 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 windows which are not constrained to the size of the
screen and whose contents need not be completely displayed.
See curspad(3CURSES) for more information.
In addition to drawing characters on the screen, video
attributes and colors may be included, causing the charac-
ters 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 , 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
SunOS 5.11 Last change: 23 Oct 2001 2
Curses Library Functions curses(3CURSES)
/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
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
The number of bytes and the number of columns to hold a
character from the supplementary character set is locale-
specific (locale category LCTYPE) 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 screen is not desirable.
Overwriting characters (addch, for example) operates on a
screen level. Overwriting a character by a character that
requires a different number of columns may produce orphaned
columns. These orphaned columns are filled with background
characters.
SunOS 5.11 Last change: 23 Oct 2001 3
Curses Library Functions curses(3CURSES)
Inserting characters (insch, for example) operates on a
character level (that is, at the character boundaries). The
specified character is inserted right before the character,
regardless of which 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 (delch,
for example) operates on a character level (that is, at the
character boundaries). The character at the cursor is
deleted whichever column of the character the cursor points
to. Before deletion, the cursor position is adjusted to the
first column of the character.
A multi-column character cannot be put on the last column of
a line. When such attempts are made, the last column is set
to the background character. In addition, when such an
operation creates orphaned columns, the orphaned columns are
filled with background characters.
Overlapping and overwriting a window follows the operation
of overwriting characters around its edge. The orphaned
columns, if any, are handled as in 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 that
holds multiple columns, the cursor is adjusted to the first
column of the character 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 pre-
fixed 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(3CURSES) 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 coordinates.
SunOS 5.11 Last change: 23 Oct 2001 4
Curses Library Functions curses(3CURSES)
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 vari-
ables ch and attrs below are always of type chtype. The
types WINDOW, SCREN, bool, and chtype are defined in
. The type TERMINAL is defined in . 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.
curses Routine Name Manual Page Name
addch cursaddch(3CURSES)
addchnstr cursaddchstr(3CURSES)
addchstr cursaddchstr(3CURSES)
addnstr cursaddstr(3CURSES)
addnwstr cursaddwstr(3CURSES)
addstr cursaddstr(3CURSES)
addwch cursaddwch(3CURSES)
addwchnstr cursaddwchstr(3CURSES)
addwchstr cursaddwchstr(3CURSES)
addwstr cursaddwstr(3CURSES)
adjcurspos cursalecompat(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 5
Curses Library Functions curses(3CURSES)
attroff cursattr(3CURSES)
attron cursattr(3CURSES)
attrset cursattr(3CURSES)
baudrate curstermattrs(3CURSES)
beep cursbeep(3CURSES)
bkgd cursbkgd(3CURSES)
bkgdset cursbkgd(3CURSES)
border cursborder(3CURSES)
box cursborder(3CURSES)
canchangecolor curscolor(3CURSES)
cbreak cursinopts(3CURSES)
clear cursclear(3CURSES)
clearok cursoutopts(3CURSES)
clrtobot cursclear(3CURSES)
clrtoeol cursclear(3CURSES)
colorcontent curscolor(3CURSES)
copywin cursoverlay(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 6
Curses Library Functions curses(3CURSES)
cursset curskernel(3CURSES)
defprogmode curskernel(3CURSES)
defshellmode curskernel(3CURSES)
delcurterm cursterminfo(3CURSES)
delayoutput cursutil(3CURSES)
delch cursdelch(3CURSES)
deleteln cursdeleteln(3CURSES)
delscreen cursinitscr(3CURSES)
delwin curswindow(3CURSES)
derwin curswindow(3CURSES)
doupdate cursrefresh(3CURSES)
dupwin curswindow(3CURSES)
echo cursinopts(3CURSES)
echochar cursaddch(3CURSES)
echowchar cursaddwch(3CURSES)
endwin cursinitscr(3CURSES)
erase cursclear(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 7
Curses Library Functions curses(3CURSES)
erasechar curstermattrs(3CURSES)
filter cursutil(3CURSES)
flash cursbeep(3CURSES)
flushinp cursutil(3CURSES)
getbegyx cursgetyx(3CURSES)
getch cursgetch(3CURSES)
getmaxyx cursgetyx(3CURSES)
getnwstr cursgetwstr(3CURSES)
getparyx cursgetyx(3CURSES)
getstr cursgetstr(3CURSES)
getsyx curskernel(3CURSES)
getwch cursgetwch(3CURSES)
getwin cursutil(3CURSES)
getwstr cursgetwstr(3CURSES)
getyx cursgetyx(3CURSES)
halfdelay cursinopts(3CURSES)
hascolors curscolor(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 8
Curses Library Functions curses(3CURSES)
hasic curstermattrs(3CURSES)
hasil curstermattrs(3CURSES)
idcok cursoutopts(3CURSES)
idlok cursoutopts(3CURSES)
immedok cursoutopts(3CURSES)
inch cursinch(3CURSES)
inchnstr cursinchstr(3CURSES)
inchstr cursinchstr(3CURSES)
initcolor curscolor(3CURSES)
initpair curscolor(3CURSES)
initscr cursinitscr(3CURSES)
innstr cursinstr(3CURSES)
innwstr cursinwstr(3CURSES)
insch cursinsch(3CURSES)
insdelln cursdeleteln(3CURSES)
insertln cursdeleteln(3CURSES)
insnstr cursinsstr(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 9
Curses Library Functions curses(3CURSES)
insnwstr cursinswstr(3CURSES)
insstr cursinsstr(3CURSES)
instr cursinstr(3CURSES)
inswch cursinswch(3CURSES)
inswstr cursinswstr(3CURSES)
intrflush cursinopts(3CURSES)
inwch cursinwch(3CURSES)
inwchnstr cursinwchstr(3CURSES)
inwchstr cursinwchstr(3CURSES)
inwstr cursinwstr(3CURSES)
islinetouched curstouch(3CURSES)
iswintouched curstouch(3CURSES)
isendwin cursinitscr(3CURSES)
keyname cursutil(3CURSES)
keypad cursinopts(3CURSES)
killchar curstermattrs(3CURSES)
leaveok cursoutopts(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 10
Curses Library Functions curses(3CURSES)
longname curstermattrs(3CURSES)
meta cursinopts(3CURSES)
move cursmove(3CURSES)
movenextch cursalecompat(3CURSES)
moveprevch cursalecompat(3CURSES)
mvaddch cursaddch(3CURSES)
mvaddchnstr cursaddchstr(3CURSES)
mvaddchstr cursaddchstr(3CURSES)
mvaddnstr cursaddstr(3CURSES)
mvaddnwstr cursaddwstr(3CURSES)
mvaddstr cursaddstr(3CURSES)
mvaddwch cursaddwch(3CURSES)
mvaddwchnstr cursaddwchstr(3CURSES)
mvaddwchstr cursaddwchstr(3CURSES)
mvaddwstr cursaddwstr(3CURSES)
mvcur cursterminfo(3CURSES)
mvdelch cursdelch(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 11
Curses Library Functions curses(3CURSES)
mvderwin curswindow(3CURSES)
mvgetch cursgetch(3CURSES)
mvgetnwstr cursgetwstr(3CURSES)
mvgetstr cursgetstr(3CURSES)
mvgetwch cursgetwch(3CURSES)
mvgetwstr cursgetwstr(3CURSES)
mvinch cursinch(3CURSES)
mvinchnstr cursinchstr(3CURSES)
mvinchstr cursinchstr(3CURSES)
mvinnstr cursinstr(3CURSES)
mvinnwstr cursinwstr(3CURSES)
mvinsch cursinsch(3CURSES)
mvinsnstr cursinsstr(3CURSES)
mvinsnwstr cursinswstr(3CURSES)
mvinsstr cursinsstr(3CURSES)
mvinstr cursinstr(3CURSES)
mvinswch cursinswch(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 12
Curses Library Functions curses(3CURSES)
mvinswstr cursinswstr(3CURSES)
mvinwch cursinwch(3CURSES)
mvinwchnstr cursinwchstr(3CURSES)
mvinwchstr cursinwchstr(3CURSES)
mvinwstr cursinwstr(3CURSES)
mvprintw cursprintw(3CURSES)
mvscanw cursscanw(3CURSES)
mvwaddch cursaddch(3CURSES)
mvwaddchnstr cursaddchstr(3CURSES)
mvwaddchstr cursaddchstr(3CURSES)
mvwaddnstr cursaddstr(3CURSES)
mvwaddnwstr cursaddwstr(3CURSES)
mvwaddstr cursaddstr(3CURSES)
mvwaddwch cursaddwch(3CURSES)
mvwaddwchnstr cursaddwchstr(3CURSES)
mvwaddwchstr cursaddwchstr(3CURSES)
mvwaddwstr cursaddwstr(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 13
Curses Library Functions curses(3CURSES)
mvwdelch cursdelch(3CURSES)
mvwgetch cursgetch(3CURSES)
mvwgetnwstr cursgetwstr(3CURSES)
mvwgetstr cursgetstr(3CURSES)
mvwgetwch cursgetwch(3CURSES)
mvwgetwstr cursgetwstr(3CURSES)
mvwin curswindow(3CURSES)
mvwinch cursinch(3CURSES)
mvwinchnstr cursinchstr(3CURSES)
mvwinchstr cursinchstr(3CURSES)
mvwinnstr cursinstr(3CURSES)
mvwinnwstr cursinwstr(3CURSES)
mvwinsch cursinsch(3CURSES)
mvwinsnstr cursinsstr(3CURSES)
mvwinsstr cursinsstr(3CURSES)
mvwinstr cursinstr(3CURSES)
mvwinswch cursinswch(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 14
Curses Library Functions curses(3CURSES)
mvwinswstr cursinswstr(3CURSES)
mvwinwch cursinwch(3CURSES)
mvwinwchnstr cursinwchstr(3CURSES)
mvwinwchstr cursinwchstr(3CURSES)
mvwinwstr cursinwstr(3CURSES)
mvwprintw cursprintw(3CURSES)
mvwscanw cursscanw(3CURSES)
napms curskernel(3CURSES)
newpad curspad(3CURSES)
newterm cursinitscr(3CURSES)
newwin curswindow(3CURSES)
nl cursoutopts(3CURSES)
nocbreak cursinopts(3CURSES)
nodelay cursinopts(3CURSES)
noecho cursinopts(3CURSES)
nonl cursoutopts(3CURSES)
noqiflush cursinopts(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 15
Curses Library Functions curses(3CURSES)
noraw cursinopts(3CURSES)
notimeout cursinopts(3CURSES)
overlay cursoverlay(3CURSES)
overwrite cursoverlay(3CURSES)
paircontent curscolor(3CURSES)
pechochar curspad(3CURSES)
pechowchar curspad(3CURSES)
pnoutrefresh curspad(3CURSES)
prefresh curspad(3CURSES)
printw cursprintw(3CURSES)
putp cursterminfo(3CURSES)
putwin cursutil(3CURSES)
qiflush cursinopts(3CURSES)
raw cursinopts(3CURSES)
redrawwin cursrefresh(3CURSES)
refresh cursrefresh(3CURSES)
resetprogmode curskernel(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 16
Curses Library Functions curses(3CURSES)
resetshellmode curskernel(3CURSES)
resetty curskernel(3CURSES)
restartterm cursterminfo(3CURSES)
ripoffline curskernel(3CURSES)
savetty curskernel(3CURSES)
scanw cursscanw(3CURSES)
scrdump cursscrdump(3CURSES)
scrinit cursscrdump(3CURSES)
scrrestore cursscrdump(3CURSES)
scrset cursscrdump(3CURSES)
scroll cursscroll(3CURSES)
scrollok cursoutopts(3CURSES)
setcurterm cursterminfo(3CURSES)
setterm cursinitscr(3CURSES)
setscrreg cursoutopts(3CURSES)
setsyx curskernel(3CURSES)
setterm cursterminfo(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 17
Curses Library Functions curses(3CURSES)
setupterm cursterminfo(3CURSES)
slkattroff cursslk(3CURSES)
slkattron cursslk(3CURSES)
slkattrset cursslk(3CURSES)
slkclear cursslk(3CURSES)
slkinit cursslk(3CURSES)
slklabel cursslk(3CURSES)
slknoutrefresh cursslk(3CURSES)
slkrefresh cursslk(3CURSES)
slkrestore cursslk(3CURSES)
slkset cursslk(3CURSES)
slktouch cursslk(3CURSES)
srcl cursscroll(3CURSES)
standend cursattr(3CURSES)
standout cursattr(3CURSES)
startcolor curscolor(3CURSES)
subpad curspad(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 18
Curses Library Functions curses(3CURSES)
subwin curswindow(3CURSES)
syncok curswindow(3CURSES)
termattrs curstermattrs(3CURSES)
termname curstermattrs(3CURSES)
tgetent curstermcap(3CURSES)
tgetflag curstermcap(3CURSES)
tgetnum curstermcap(3CURSES)
tgetstr curstermcap(3CURSES)
tgoto curstermcap(3CURSES)
tigetflag cursterminfo(3CURSES)
tigetnum cursterminfo(3CURSES)
tigetstr cursterminfo(3CURSES)
timeout cursinopts(3CURSES)
touchline curstouch(3CURSES)
touchwin curstouch(3CURSES)
tparm cursterminfo(3CURSES)
tputs cursterminfo(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 19
Curses Library Functions curses(3CURSES)
typeahead cursinopts(3CURSES)
unctrl cursutil(3CURSES)
ungetch cursgetch(3CURSES)
ungetwch cursgetwch(3CURSES)
untouchwin curstouch(3CURSES)
useenv cursutil(3CURSES)
vidattr cursterminfo(3CURSES)
vidputs cursterminfo(3CURSES)
vwprintw cursprintw(3CURSES)
vwscanw cursscanw(3CURSES)
waddch cursaddch(3CURSES)
waddchnstr cursaddchstr(3CURSES)
waddchstr cursaddchstr(3CURSES)
waddnstr cursaddstr(3CURSES)
waddnwstr cursaddwstr(3CURSES)
waddstr cursaddstr(3CURSES)
waddwch cursaddwch(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 20
Curses Library Functions curses(3CURSES)
waddwchnstr cursaddwchstr(3CURSES)
waddwchstr cursaddwchstr(3CURSES)
waddwstr cursaddwstr(3CURSES)
wadjcurspos cursalecompat(3CURSES)
wattroff cursattr(3CURSES)
wattron cursattr(3CURSES)
wattrset cursattr(3CURSES)
wbkgd cursbkgd(3CURSES)
wbkgdset cursbkgd(3CURSES)
wborder cursborder(3CURSES)
wclear cursclear(3CURSES)
wclrtobot cursclear(3CURSES)
wclrtoeol cursclear(3CURSES)
wcursyncup curswindow(3CURSES)
wdelch cursdelch(3CURSES)
wdeleteln cursdeleteln(3CURSES)
wechochar cursaddch(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 21
Curses Library Functions curses(3CURSES)
wechowchar cursaddwch(3CURSES)
werase cursclear(3CURSES)
wgetch cursgetch(3CURSES)
wgetnstr cursgetstr(3CURSES)
wgetnwstr cursgetwstr(3CURSES)
wgetstr cursgetstr(3CURSES)
wgetwch cursgetwch(3CURSES)
wgetwstr cursgetwstr(3CURSES)
whline cursborder(3CURSES)
winch cursinch(3CURSES)
winchnstr cursinchstr(3CURSES)
winchstr cursinchstr(3CURSES)
winnstr cursinstr(3CURSES)
winnwstr cursinwstr(3CURSES)
winsch cursinsch(3CURSES)
winsdelln cursdeleteln(3CURSES)
winsertln cursdeleteln(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 22
Curses Library Functions curses(3CURSES)
winsnstr cursinsstr(3CURSES)
winsnwstr cursinswstr(3CURSES)
winsstr cursinsstr(3CURSES)
winstr cursinstr(3CURSES)
winswch cursinswch(3CURSES)
winswstr cursinswstr(3CURSES)
winwch cursinwch(3CURSES)
winwchnstr cursinwchstr(3CURSES)
winwchstr cursinwchstr(3CURSES)
winwstr cursinwstr(3CURSES)
wmove cursmove(3CURSES)
wmovenextch cursalecompat(3CURSES)
wmoveprevch cursalecompat(3CURSES)
wnoutrefresh cursrefresh(3CURSES)
wprintw cursprintw(3CURSES)
wredrawln cursrefresh(3CURSES)
wrefresh cursrefresh(3CURSES)
SunOS 5.11 Last change: 23 Oct 2001 23
Curses Library Functions curses(3CURSES)
wscanw cursscanw(3CURSES)
wscrl cursscroll(3CURSES)
wsetscrreg cursoutopts(3CURSES)
wstandend cursattr(3CURSES)
wstandout cursattr(3CURSES)
wsyncdown curswindow(3CURSES)
wsyncup curswindow(3CURSES)
wtimeout cursinopts(3CURSES)
wtouchln curstouch(3CURSES)
wvline cursborder(3CURSES)
RETURN VALUES
Routines that return an integer return ER upon failure and
an integer value other than ER upon successful completion,
unless otherwise noted in the routine descriptions.
All macros return the value of the w version, except
setscrreg(), wsetscrreg(), getyx(), getbegyx(), and get-
maxyx(). 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 assign-
ment statements).
Routines that return pointers return NUL on error.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 23 Oct 2001 24
Curses Library Functions curses(3CURSES)
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Unsafe
SEE ALSO
curses(3XCURSES), libcurses(3LIB), libcurses(3XCURSES), ter-
minfo(4), attributes(5)
NOTES
The header automatically includes the headers
and .
SunOS 5.11 Last change: 23 Oct 2001 25
|
